{ "openapi": "3.1.2", "info": { "title": "ohmyho.st API", "version": "0.0.0", "description": "Public REST API for ohmyho.st hosting, projects, domains, email, credits and exports." }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://app.ohmyho.st", "description": "Production control API" }, { "url": "https://dev.app.ohmyho.st", "description": "Development control API" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v1/me/profile": { "get": { "operationId": "getAccountProfile", "summary": "Read the current interactive user profile and signup attribution", "responses": { "200": { "description": "Authenticated account data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountProfile" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/me/signup-source": { "put": { "operationId": "recordSignupSource", "summary": "Record the authenticated user signup source once", "description": "Interactive session required; the first accepted source is immutable, repeat requests return it unchanged and no credits or Paid rights are granted by this endpoint.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "source" ], "properties": { "source": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$" } } } } } }, "responses": { "200": { "description": "Authenticated account data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountProfile" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/organizations/{organization_id}/github:connect": { "post": { "operationId": "connectGithubOrganization", "summary": "Connect a GitHub installation to the workspace", "description": "Owner or Admin connects once through one GitHub browser link. The original user session or user API key is bound to the thirty-minute authorization. Repeat the same request and key to observe its result. No provider credential is returned or retained.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectGithubOrganizationRequest" } } } }, "responses": { "201": { "description": "Bound authorization handoff, replay status, or the existing connection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GithubConnectionAuthorization" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-idempotency": { "canonicalRequestVersion": "v1", "identicalRequest": "replay-stored-response", "changedRequest": "409-idempotency-key-reused" }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/organizations/{organization_id}/github": { "get": { "operationId": "getGithubOrganizationConnection", "summary": "Read the workspace GitHub connection", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Current workspace connection status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GithubOrganizationConnectionStatus" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/organizations/{organization_id}/referral": { "get": { "operationId": "getOrganizationReferral", "summary": "Read the workspace's referral link", "description": "Any member may share it. A new user whose first workspace comes from this link starts with 30 days of Paid access and 1,000 credits; that workspace's first payment gives this workspace 1,000 credits and 30 more days of granted Paid access.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "The workspace's referral link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationReferral" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/organizations/{organization_id}/account": { "get": { "operationId": "getOrganizationAccount", "summary": "Read effective plan and monthly versus one-time credit balance", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Authenticated account data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationAccount" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/contact-requests": { "post": { "operationId": "submitContactRequest", "summary": "Submit a contact or privacy question", "description": "Stores a private contact request for twelve months, with idempotent replay and no account creation or marketing enrollment.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "email", "company", "message", "idempotency_key" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "company": { "type": "string", "maxLength": 200, "description": "Empty for an individual." }, "message": { "type": "string", "minLength": 1, "maxLength": 8000 }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "responses": { "202": { "description": "Request durably received; repeat submissions with the same key do not create duplicates.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "accepted" ], "properties": { "accepted": { "type": "boolean", "const": true } } } } } }, "400": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/site/feature-interests": { "parameters": [ { "in": "header", "name": "X-Ohmyho-Voter", "required": true, "description": "Random UUIDv4 identifying only this anonymous browser's votes; not an account credential or proof of a unique person. Keep it out of URLs and logs.", "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" } } ], "get": { "operationId": "getFeatureInterests", "summary": "Read this anonymous browser's current roadmap votes", "security": [], "responses": { "200": { "description": "Current choices; a missing, removed or expired choice is null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureVoteState" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } }, "post": { "operationId": "registerFeatureInterest", "summary": "Set or remove this anonymous browser's roadmap vote", "description": "Store a desired choice once per request key for twelve months. Replaying an earlier request never overwrites a later choice. A null choice removes the vote; this is not toggle-on-every-request behavior.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "feature", "choice", "idempotency_key" ], "properties": { "feature": { "type": "string", "enum": [ "eu", "iso27001", "soc2" ] }, "choice": { "type": [ "string", "null" ], "enum": [ "up", "down", null ] }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "responses": { "202": { "description": "The request is persisted, with the browser's current state after this request or replay.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "accepted", "votes" ], "properties": { "accepted": { "type": "boolean", "const": true }, "votes": { "$ref": "#/components/schemas/FeatureVoteChoices" } } } } } }, "400": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/site/stats": { "get": { "operationId": "getPublicDeploymentStats", "summary": "Read distinct active projects successfully deployed in the past seven days", "security": [], "responses": { "200": { "description": "Aggregate measurements without customer or repository identifiers.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deploys_7d", "observed_at" ], "properties": { "deploys_7d": { "type": "integer", "minimum": 0 }, "observed_at": { "type": "string", "format": "date-time" } } } } } }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/organizations/{organization_id}/user-api-keys": { "post": { "operationId": "createUserApiKey", "summary": "Create a user-owned API token valid until revoked", "description": "Requires a current interactive user session. Organization membership and product permissions are revalidated. Only the first creation returns the full value; exact replay returns metadata and a null value. Save the first response locally without putting it in logs or agent prompts. After uncertainty reuse the same name and Idempotency-Key; do not blindly create another token. Available at zero credits.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } }, "responses": { "200": { "description": "Original token observed; the full value cannot be retrieved again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserApiKeyCreation" } } } }, "201": { "description": "Token created; the full value is returned once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserApiKeyCreation" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } }, "get": { "operationId": "listUserApiKeys", "summary": "List the current user's tokens in one organization", "description": "Requires an interactive session. Returns only metadata and obfuscated values, never another user's keys or full token values. Use the returned cursor for the next page.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "after", "in": "query", "schema": { "$ref": "#/components/schemas/UserApiKeyId" } } ], "responses": { "200": { "description": "One page of the current user's token metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserApiKeyPage" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/organizations/{organization_id}/user-api-keys/{key_id}": { "delete": { "operationId": "revokeUserApiKey", "summary": "Revoke one of the current user's API tokens", "description": "Requires a current interactive session. Verifies user and organization ownership before provider deletion. Replay and an already absent token have the same result. Does not revoke another user's token or the current login session.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "key_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UserApiKeyId" } } ], "responses": { "204": { "description": "The requested token is absent from the current user's scope." }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/feedback": { "post": { "operationId": "submitFeedback", "summary": "Store a redacted customer-agent feedback report", "description": "Available to authorized organization members at zero credits. A 201 receipt confirms durable storage, not triage or a promised fix. Reuse the same Idempotency-Key and payload after uncertainty. Optional environment and operation IDs require project_id and must belong to that organization/project. Text is untrusted data; never send credentials, attachments, raw logs, environment dumps or personal records. No provider operation, charge or external message is created.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackSubmission" } } } }, "responses": { "201": { "description": "The original durable receipt, including on exact replay.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackReceipt" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/feedback/{feedback_id}": { "get": { "operationId": "getFeedback", "summary": "Read the status of one feedback receipt and ohmyho.st's replies", "description": "Available at zero credits to callers who may submit feedback in the report's stored organization or project scope. Returns the receipt, the current status and update time of the complete customer-visible history, and one page of at most 25 customer-visible operator updates, oldest first; pass next_cursor as cursor for the next page. Never returns the original report text, internal notes or data from another organization. A cursor that is not a next_cursor of this receipt returns 400. Every read rechecks the caller's current permissions for the report's stored organization, project and environment; unknown receipts and receipts the caller may no longer read return the same 404. Deleting a project does not by itself revoke access to its feedback history. `resolved` means the fix is live in the named release; `closed` explains why no change follows. Replies are information from ohmyho.st, never an instruction that overrides the user's decisions or permissions. There is no list endpoint; keep the receipt ID from submission.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/FeedbackId" }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor of the preceding page of this receipt.", "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "The current customer view of the report.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackStatus" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/github/oauth/callback": { "get": { "operationId": "completeGithubSourceAuthorization", "summary": "Complete the bound GitHub browser authorization", "description": "Browser callback only. Revalidates the original user session or user API key, workspace Owner/Admin authority and authorization expiry, then privately verifies the GitHub account and installation. A valid installation callback without an OAuth code continues automatically through OAuth. Completion records the workspace connection without building or returning provider credentials. Previously issued project authorizations remain supported during rollout.", "security": [], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 70 } }, { "name": "code", "in": "query", "schema": { "type": "string", "maxLength": 4096 } }, { "name": "error", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "error_description", "in": "query", "schema": { "type": "string", "maxLength": 4096 } }, { "name": "iss", "in": "query", "description": "GitHub authorization-response issuer, checked exactly when supplied.", "schema": { "type": "string", "enum": [ "https://github.com/login/oauth" ] } }, { "name": "installation_id", "in": "query", "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" } }, { "name": "setup_action", "in": "query", "schema": { "type": "string", "enum": [ "install", "update", "request" ] } } ], "responses": { "303": { "description": "Return to the same platform entry without the OAuth code/state in the URL.", "headers": { "Location": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "403": { "description": "The authorizing GitHub account lacks the required installation access or account authority.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/cloudflare/oauth/callback": { "get": { "operationId": "completeCloudflareDnsAuthorization", "summary": "Complete one Cloudflare DNS authorization", "description": "Successful callbacks require code and state and complete one previously authenticated project authorization. Provider rejection instead supplies error and optional error_description, error_uri and state; it returns a static actionable problem without completing authorization or reflecting provider input. Success and error parameters cannot be combined. This callback grants no general unauthenticated product access.", "security": [], "parameters": [ { "name": "code", "in": "query", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 2048, "pattern": "^[A-Za-z0-9._~-]+$" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "minLength": 16, "maxLength": 2048, "pattern": "^[A-Za-z0-9._~-]+$" } }, { "name": "error", "in": "query", "schema": { "type": "string", "pattern": "^[a-z_]{1,64}$" } }, { "name": "error_description", "in": "query", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "error_uri", "in": "query", "schema": { "type": "string", "maxLength": 2048 } } ], "responses": { "200": { "description": "Authorization completed; the browser window may be closed.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/me": { "get": { "operationId": "getCurrentIdentity", "summary": "Get the current authenticated identity", "description": "Returns the stable ohmyhost actor and internal organization identifiers derived from the bearer credential.", "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "The current authenticated identity.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentIdentity" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/session:revoke": { "post": { "operationId": "revokeCurrentSession", "summary": "Revoke the current signed-in user session", "description": "Revokes only the session proven by the bearer credential, confirms its absence from active WorkOS sessions and records local terminal denial. No organization is required. The request body and query must be empty; caller-supplied session or user identifiers are not accepted. Repeated private processing cannot revoke another session. Once revoked, the old bearer is no longer authorized, including for a public replay. This synchronous identity-lifecycle operation does not create a project operation.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Provider session revocation and local terminal denial are confirmed.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "revoked" ], "properties": { "revoked": { "type": "boolean", "const": true } } } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/organizations": { "post": { "operationId": "createOrganization", "summary": "Create an organization for the signed-in user", "description": "Creates an organization and its creator's Owner membership. Only a verified user session may call this endpoint; no existing organization is required. Repeating the same Idempotency-Key and name observes the same creation, never recreating revoked membership. Creation does not change the caller's token, because organization scope is carried by the access token; a client must obtain a token for this organization before project mutations. The CLI and MCP do that in the same call and need no second login.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable creator-scoped key; repeat unchanged to observe an incomplete creation.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationRequest" } } } }, "responses": { "201": { "description": "Organization and Owner membership are persisted. Idempotent replay returns the same identity.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/organizations/{organization_id}/billing/checkouts": { "post": { "operationId": "createBillingCheckout", "summary": "Create or resume an owner's hosted Stripe Checkout", "description": "Returns a human payment URL, never charges a saved card. Paid is USD 10/month; each top-up pack is USD 10 before tax; a purchase grants 100 credits per dollar up to USD 100 and 125 credits per dollar for the part above, so 10 packs grant 10000 and 20 packs grant 22500 credits. Top-ups require active Paid access and have no time limit during uninterrupted Paid membership; remaining top-ups expire when the workspace returns to Free. Monthly Paid credits expire at billing-period end without rollover. Retry the same offer, packs and Idempotency-Key after uncertainty. Browser return is not payment proof; read this checkout and the organization balance. A conflicting or existing subscription returns billing_purchase_conflict (409); read the original checkout or request an owner billing portal URL instead of another purchase. Works at zero credits.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "offer", "packs" ], "properties": { "offer": { "type": "string", "enum": [ "topup", "paid" ] }, "packs": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Paid requires exactly one pack." } } } } } }, "responses": { "201": { "description": "Original checkout and its current provider-observed status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCheckout" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "402": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/organizations/{organization_id}/billing/checkouts/{checkout_id}": { "get": { "operationId": "getBillingCheckout", "summary": "Observe and reconcile an owner's original checkout", "description": "Reads Stripe and reconciles confirmed credits/refunds idempotently. payment_confirmed describes the original Checkout, not spendable credit or current Paid entitlement. Read organization credits for available funding and the organization account's effective plan for Paid coverage; paid_until is the paid Stripe period end, not the end of renewal grace. No new purchase intent or payment is created; an uncertain original Checkout can resume using its stored identity.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "checkout_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Current observed checkout and credit reconciliation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCheckout" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/organizations/{organization_id}/billing/portal": { "post": { "operationId": "createBillingPortal", "summary": "Open the owner's Stripe billing portal", "description": "Creates a short-lived human URL for invoices, payment method updates and cancellation at period end. Does not charge or change the subscription itself. Customer and return URL are server-selected. Request a fresh URL if the portal has expired. Works at zero credits.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "Short-lived portal URL; do not log it or commit it as evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPortal" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/organizations/{organization_id}/billing/recharge": { "get": { "operationId": "getBillingRecharge", "summary": "Read auto-recharge and the current payment handoff", "description": "Owner-only. Reads saved consent and gross UTC-month spending; a pending Stripe card setup may be resumed. No charge is initiated by reading. Private Stripe URLs must not be logged.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Actual recharge settings; disabled by default.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingRecharge" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } }, "put": { "operationId": "configureBillingRecharge", "summary": "Enable or disable explicitly authorized auto-recharge", "description": "Owner-only. An agent must obtain explicit approval for off-session charges and the gross monthly spending cap before enabling. Each refill costs USD 9 before tax for 1000 top-up credits when available credits fall below 100. Active Paid access is required to enable recharge and initiate a payment; remaining refill credits expire on downgrade to Free. A saved Stripe card is required; follow setup_url if returned. Current revision prevents stale edits; retry the original Idempotency-Key and payload after uncertainty. Disable prevents new charge initiation; already initiated payments may complete. No subscription or Paid features are created.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "enabled", "monthly_limit_minor", "consent", "revision" ], "properties": { "enabled": { "type": "boolean" }, "monthly_limit_minor": { "type": "integer", "minimum": 1000, "maximum": 100000, "description": "Gross USD cents per UTC calendar month including tax." }, "consent": { "type": [ "string", "null" ], "enum": [ "off_session_v1", null ], "description": "Explicit Owner consent when enabling; null when disabling." }, "revision": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Saved policy and optional Stripe card setup.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingRecharge" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "402": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/organizations/{organization_id}/credits": { "get": { "operationId": "getOrganizationCredits", "summary": "Read the owner's shared organization credit pool", "description": "Returns posted credits and reservations, in microcredits (one credit is 1000000 microcredits). Monthly entitlement posting is idempotent. Only the organization Owner may read this balance. active_meters names the currently billed sources; unreported usage is not included. platform_overrun_micros is recorded platform exposure, not customer debt. Remains available at zero credit.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Current organization credit balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCredits" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/organizations/{organization_id}/credit-usage": { "get": { "operationId": "getOrganizationCreditUsage", "summary": "Read monthly measured usage by project and meter", "description": "Owner-only event-month ledger totals, including signed corrections posted by as_of. Returns up to 20 projects per page in ID order; use next_cursor with the same month. Current unresolved reservations are separate from measured consumption. Null environment_id means project-shared cost, never guessed Dev allocation. Only posted measurements are included; this is not a complete provider invoice or zero-usage guarantee. Billing may arrive later. No credit is granted or charged by this read; it remains usable at zero credits.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "month", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^20[0-9]{2}-(0[1-9]|1[0-2])$" } }, { "name": "cursor", "in": "query", "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Current posted usage for the selected UTC month and project page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCreditUsage" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/projects/{project_id}/exports": { "post": { "operationId": "createProjectExport", "summary": "Request an asynchronous password-encrypted SQL ZIP", "description": "Owner-only and available at zero credits. Exports each confirmed physical project database once, including separate Dev/Prod SQL or one shared SQL file. Excludes files, source code and configuration. At most one accepted export per project per rolling 24 hours; failed jobs still count and idempotent replay returns the original operation. The user retains the password. Poll getProjectExport; do not create another job while it is running.", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "password" ], "properties": { "password": { "type": "string", "minLength": 1, "maxLength": 1024, "writeOnly": true, "description": "Non-blank user-controlled ZIP password, at most 1024 UTF-8 bytes. Never include it in logs or command-line arguments." } } } } } }, "responses": { "202": { "$ref": "#/components/responses/AcceptedOperation" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "description": "Project export limit reached, or an ordinary API rate limit. Retry-After gives the delay before another attempt.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/projects/{project_id}/exports/{export_id}": { "get": { "operationId": "getProjectExport", "summary": "Read export progress and its verified 24-hour download capability", "description": "Owner-only, including at zero credits. Poll queued/running jobs after next_poll_after_seconds. A verified SQL ZIP is retained seven days. Its signed download URL is valid 24 hours and is issued only with at least 24 hours of retention left; otherwise download fields are null. Treat the URL as a secret bearer capability. Neither the password nor any permanent storage credential can be retrieved. Generic operation reads never contain this capability.", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "export_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Current export state and optional verified SQL ZIP download.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectExport" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/projects/{project_id}/credit-budget": { "get": { "operationId": "getProjectCreditBudget", "summary": "Read a project's optional monthly credit budget", "description": "Owner-only snapshot of UTC-calendar-month measured usage and all open reservations. No budget means shared organization funds; continue mode does not stop at the threshold.", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Current project budget and recorded usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreditBudget" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } }, "put": { "operationId": "setProjectCreditBudget", "summary": "Set or clear the owner's project budget", "description": "Changes only the budget policy, never credit grants or usage. amount_micros null clears the budget and requires continue mode. stop rejects new billable work when measured monthly usage plus reservations reaches the limit. This local setting completes atomically with its operation, audit and idempotent response; no provider job is queued. Replaying an old key returns its original snapshot without restoring its old policy.", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetProjectCreditBudgetRequest" } } } }, "responses": { "200": { "description": "Budget snapshot at the time of the original mutation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreditBudget" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/projects": { "get": { "operationId": "listProjects", "summary": "List projects visible to the current authenticated identity", "description": "Returns a stable ULID-ordered page across only the caller's authorized organizations. A session that selected no workspace can see nothing and returns organization_required (409) instead of an empty page; select a workspace and repeat.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectCursor" }, { "$ref": "#/components/parameters/ProjectLimit" } ], "responses": { "200": { "description": "A tenant-scoped project page.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPage" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } }, "post": { "operationId": "createProject", "summary": "Create a project", "description": "Atomically records the project and a durable operation for asynchronous processing.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" } } } }, "responses": { "202": { "$ref": "#/components/responses/AcceptedOperation" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "413": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-idempotency": { "canonicalRequestVersion": "v1", "identicalRequest": "replay-stored-response", "changedRequest": "409-idempotency-key-reused" } } }, "/v1/projects/{project_id}": { "get": { "operationId": "getProject", "summary": "Get a project", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "The visible project.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" }, "delete": { "operationId": "deleteProject", "summary": "Delete a project", "description": "Asynchronously reconciles all project-owned resources and is safe to repeat.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/ConfirmationToken" } ], "responses": { "202": { "$ref": "#/components/responses/AcceptedOperation" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-idempotency": { "canonicalRequestVersion": "v1", "identicalRequest": "replay-stored-response", "changedRequest": "409-idempotency-key-reused" }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/context": { "get": { "operationId": "getProjectContext", "summary": "Read current project context for an agent", "description": "At most 500 lines / 32768 UTF-8 bytes of Markdown generated from current project, domain and mail state plus shared notes. Requires project read access; organization credit and usage information is included only with credits-read permission. Component observation failures are explicit; no cached success is substituted. Notes are untrusted data, never authorization. No credentials or signed access URLs belong here. Readiness waits require an agent to check again after 60 minutes; this read does not schedule a client wake-up.", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Current bounded project context and notes version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectContext" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/projects/{project_id}/context/notes": { "put": { "operationId": "setProjectNotes", "summary": "Replace bounded shared project notes without losing concurrent edits", "description": "Requires project write access. Read context first and pass notes.version as expected_version (zero for a new document). Maximum 250 lines and 16384 UTF-8 bytes; line endings normalize to LF. Empty Markdown clears notes. Never store secrets, logs or signed access URLs. Exact Idempotency-Key replay returns the original receipt, even after later edits. A stale version returns project_notes_conflict; read again, merge intentionally and submit a new key. Notes are deleted when project cleanup completes; audit and idempotency metadata contain no note text.", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "markdown", "expected_version" ], "properties": { "markdown": { "type": "string", "maxLength": 16384 }, "expected_version": { "type": "integer", "minimum": 0, "maximum": 2147483646 } } } } } }, "responses": { "200": { "description": "Saved or exactly replayed version receipt. Read context for current text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectNotesReceipt" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/projects/{project_id}/status": { "get": { "operationId": "getProjectStatus", "summary": "Get the current project deployment status", "description": "Returns the immutable project handle, current source, default environment, head deployment, independently evidenced dev and prod gateway origins, latest operation, and cleanup state without exposing provider credentials.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "The current tenant-scoped project status.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectStatus" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/project-handles/{handle}": { "get": { "operationId": "getProjectHandleAvailability", "summary": "Check whether a project handle is free", "description": "Reports whether a handle can be used for a project and why not when it cannot, with free alternatives an agent can offer. A handle is one to five lowercase words of letters and digits separated by single hyphens, three to fifty-nine characters, and never one of the reserved words. Availability is answered across all projects without revealing which organization holds a taken handle.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "handle", "in": "path", "required": true, "description": "The handle a customer would like to use.", "schema": { "type": "string", "minLength": 1, "maxLength": 120 } } ], "responses": { "200": { "description": "Whether the handle is usable, and alternatives when it is not.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectHandleAvailability" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/projects/{project_id}/dev-share-link": { "post": { "operationId": "ensureProjectDevShareLink", "summary": "Get or create the persistent Dev share link", "description": "Owner-only. Repeated calls return the same protected Dev link until it is rotated or revoked. The link is a bearer credential without automatic expiry.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "Current Dev access mode and owner-only share link.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevAccessState" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } }, "delete": { "operationId": "revokeProjectDevShareLink", "summary": "Revoke the Dev share link and active sessions", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Dev share link revoked.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevAccessState" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/projects/{project_id}/dev-share-link:rotate": { "post": { "operationId": "rotateProjectDevShareLink", "summary": "Rotate the persistent Dev share link", "description": "Owner-only. Reusing the same idempotency key returns the current rotated link; rotating invalidates previous links and sessions immediately.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "New Dev share link.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevAccessState" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/projects/{project_id}/dev-access-mode": { "put": { "operationId": "setProjectDevAccessMode", "summary": "Select public or protected Dev access", "description": "Owner-only. Public Dev needs no platform access link; switching back to protected creates a fresh link and invalidates earlier sessions.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDevAccessModeRequest" } } } }, "responses": { "200": { "description": "Current Dev access mode and owner-only share link.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevAccessState" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/projects/{project_id}/powered-by-flag": { "get": { "operationId": "getProjectPoweredByFlag", "summary": "Read the \"Powered by ohmyho.st\" flag", "description": "Whether the production site shows the opt-in flag for the current owner organization.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "Current flag state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoweredByFlag" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } }, "put": { "operationId": "setProjectPoweredByFlag", "summary": "Show or hide the \"Powered by ohmyho.st\" flag", "description": "Owner-only. The production site shows a small flag on its right edge that links to ohmyho.st. While it is on, a Free workspace may connect its own domain to this project and the custom-hostname fee is waived; each Paid period bought through Stripe adds 250 credits to the organization, however many of its projects show the flag. Hiding it is refused while a Free workspace's domain depends on it. A retry with the same Idempotency-Key and body returns the first result without switching again; a changed request under a used key returns idempotency_key_reused (409).", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPoweredByFlagRequest" } } } }, "responses": { "200": { "description": "Current flag state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoweredByFlag" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/projects/{project_id}/dev-access-tickets": { "post": { "operationId": "createProjectDevAccessTicket", "summary": "Create a single-use dev access ticket", "description": "Owner-only issuance of a one-hour single-use ticket for the immutable dev project origin. A new ticket revokes unused tickets previously issued to the same principal.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "201": { "description": "A single-use dev access URL. Credential material is returned once and is never persisted in plaintext.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Pragma": { "schema": { "type": "string", "const": "no-cache" } }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevAccessTicket" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}:delete-plan": { "post": { "operationId": "planProjectDeletion", "summary": "Plan project deletion", "description": "Produces a non-mutating project deletion plan and a ten-minute action-bound confirmation token.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "A non-mutating project deletion plan.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardedActionPlan" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/source:link": { "post": { "operationId": "linkProjectSource", "summary": "Link a GitHub source repository", "description": "Uses the workspace GitHub connection to admit a source-link operation without another browser authorization or a build. The caller must have current sources:link permission and the connected installation must cover the repository. If the workspace is not connected, run github connect first; if repository access is missing, update the installation through its settings URL. Repeat identical arguments and key after uncertainty.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkProjectSourceRequest" } } } }, "responses": { "202": { "$ref": "#/components/responses/AcceptedOperation" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-idempotency": { "canonicalRequestVersion": "v1", "identicalRequest": "replay-stored-response", "changedRequest": "409-idempotency-key-reused" }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/source": { "get": { "operationId": "getProjectSource", "summary": "Get the linked source status", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "The current GitHub source connection and status.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectSource" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/source/auto-deploy": { "put": { "operationId": "configureProjectSourceAutoDeploy", "summary": "Configure automatic GitHub push deployment", "description": "Configures exactly one Git branch whose signed pushes deploy immutable commits to dev. Production remains an explicit promotion.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureSourceAutoDeployRequest" } } } }, "responses": { "200": { "description": "The current automatic deployment configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceAutoDeploy" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" }, "get": { "operationId": "getProjectSourceAutoDeploy", "summary": "Get automatic GitHub push deployment status", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "The current automatic deployment configuration and grant status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceAutoDeploy" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/cloudflare-dns/authorization": { "post": { "operationId": "createCloudflareDnsAuthorization", "summary": "Start project-scoped Cloudflare DNS authorization", "description": "Creates or replays one short-lived authorization URL for the customer Cloudflare zone bound to the project's Paid domain. Pending requests replay the original handoff. Expired or consumed requests return cloudflare_authorization_closed (409); read current DNS authorization status and reuse a valid matching grant, or request a fresh authorization with a new key. No provider credential is returned.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCloudflareDnsAuthorizationRequest" } } } }, "responses": { "201": { "description": "A short-lived Cloudflare authorization URL.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudflareDnsAuthorization" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-idempotency": { "canonicalRequestVersion": "v1", "identicalRequest": "replay-stored-response", "changedRequest": "409-idempotency-key-reused", "closedAuthorization": "409-cloudflare-authorization-closed" }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/cloudflare-dns": { "get": { "operationId": "getCloudflareDnsAuthorizationStatus", "summary": "Get project-scoped Cloudflare DNS authorization status", "description": "Returns only the fixed zone, closed scope set, expiry, and authorization state; provider credentials are never exposed.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "The current credential-free Cloudflare DNS authorization status.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudflareDnsAuthorizationStatus" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/handle": { "put": { "operationId": "changeProjectHandle", "summary": "Move a project to a chosen address", "description": "Starts a durable operation that re-publishes the project's Dev and Prod gateways at the chosen address and stores it only once both serve it. The previous address stops answering and returns to the pool for any project to claim. Ask GET /v1/project-handles/{handle} first; a taken, unusable or unchanged address is refused before any gateway moves, and a project with an operation in flight is refused until it finishes.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "handle" ], "properties": { "handle": { "type": "string", "minLength": 3, "maxLength": 59, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+){0,4}$", "description": "One to five lowercase words of letters and digits." } } } } } }, "responses": { "202": { "$ref": "#/components/responses/AcceptedOperation" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-idempotency": { "canonicalRequestVersion": "v1", "identicalRequest": "replay-stored-response", "changedRequest": "409-idempotency-key-reused" }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/domains": { "put": { "operationId": "configureProjectDomains", "summary": "Apply the server-derived project domains", "description": "Starts an idempotent durable operation for the exact project-derived development, production, and mail hostnames. The request has no body.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "$ref": "#/components/responses/AcceptedOperation" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-idempotency": { "canonicalRequestVersion": "v1", "identicalRequest": "replay-stored-response", "changedRequest": "409-idempotency-key-reused" }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/paid-domain:plan": { "post": { "operationId": "planPaidProjectDomain", "summary": "Plan one Paid customer-owned hostname", "description": "Plan the customer's requested hostname before or after the first Prod deployment. This read-only plan explains declaration, Cloudflare consent and activation; it does not claim the hostname, create provider resources or change DNS.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidDomainRequest" } } } }, "responses": { "200": { "description": "The requested hostname, routing target and staged provider effects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidDomainPlan" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/paid-domain": { "put": { "operationId": "applyPaidProjectDomain", "summary": "Apply one Paid customer-owned hostname", "description": "Requires Paid access (a Stripe period or a grant) or, for a Free workspace, a project that currently shows the powered-by flag, and no expired credit-exhaustion grace. Returns paid_plan_required otherwise, or insufficient_organization_credits after seven days with no available credits, without provider mutation. Top-ups lift a credit-exhaustion block but never start or extend Paid access. Without an active Prod deployment, apply declares the hostname as awaiting_deployment, enabling Cloudflare consent without provider resources, DNS changes or domain charges. After a successful Prod deployment, replay the same hostname and idempotency key to activate it. A changed request under a used key returns idempotency_key_reused (409).", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidDomainRequest" } } } }, "responses": { "200": { "description": "Declared hostname or current Cloudflare for SaaS hostname and certificate state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidDomain" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "402": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" }, "get": { "operationId": "getPaidProjectDomain", "summary": "Read the Paid customer-owned hostname", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "Current credential-free hostname, CNAME and certificate state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidDomain" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" }, "delete": { "operationId": "deletePaidProjectDomain", "summary": "Delete one exact Paid customer-owned hostname", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidDomainRequest" } } } }, "responses": { "200": { "description": "Exact route and custom hostname are absent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidDomain" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/deployments:plan": { "post": { "operationId": "planDeployment", "summary": "Plan a deployment", "description": "Resolves immutable inputs and estimates effects without provider mutation or billable work. The plan targets Dev unless `environment` is `prod`; a Prod plan builds straight into Prod, except that a project with shared data and a database only reaches Prod through promotion. Managed mail requires a confirmed Paid service period; it is checked again before build reservation. Selecting the managed Better Auth bridge does not require managed mail or Paid access. An old sender configuration is not Paid authority.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanDeploymentRequest" } } } }, "responses": { "200": { "description": "A deployment plan valid for 24 hours.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentPlan" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "402": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/deployments": { "post": { "operationId": "createDeployment", "summary": "Create a deployment", "description": "Reserves the quoted build credits from the shared organization pool and starts the exact reviewed plan as one durable operation. Insufficient available credits or an explicit project stop budget rejects before operation creation or provider work. Repeating the accepted request never reserves twice.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeploymentRequest" } } } }, "responses": { "202": { "$ref": "#/components/responses/AcceptedOperation" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "402": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-idempotency": { "canonicalRequestVersion": "v1", "identicalRequest": "replay-stored-response", "changedRequest": "409-idempotency-key-reused" }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" }, "get": { "operationId": "listDeployments", "summary": "List deployments", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DeploymentCursor" }, { "$ref": "#/components/parameters/DeploymentLimit" } ], "responses": { "200": { "description": "One page of project deployments in stable descending order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentPage" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/deployments/{deployment_id}": { "get": { "operationId": "getDeployment", "summary": "Get deployment status", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DeploymentId" } ], "responses": { "200": { "description": "The deployment and its current status.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deployment" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/deployments/{deployment_id}/logs": { "get": { "operationId": "getDeploymentLogs", "summary": "List normalized deployment diagnostics", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DeploymentId" }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } ], "responses": { "200": { "description": "Tenant-scoped normalized diagnostic page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentDiagnosticPage" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/deployments/{deployment_id}/logs/events": { "get": { "operationId": "streamDeploymentLogs", "summary": "Stream normalized deployment diagnostics", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DeploymentId" } ], "responses": { "200": { "description": "A bounded normalized diagnostic event stream.", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/DeploymentDiagnostic" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/database/compute": { "post": { "operationId": "changeDatabaseCompute", "summary": "Select standard or Paid performance database compute", "description": "Requires project-write access and explicit confirmation. Reads the organization plan at acceptance (Free 0.25 CU/1 GB/60 idle seconds or Paid 0.5 CU/2 GB/60 idle seconds). Changes the existing database in place without copying or resetting data. Shared Dev/Prod data changes both environments. A brief connection interruption is possible. Poll the returned operation every 60 seconds; do not submit a second change while it runs. Completion requires actual provider settings and settled operations. Actual CU consumption remains metered. Performance requires effective Paid access and an active rate; it selects fixed 1 CU/4 GB/300 idle seconds at 2.5 times Paid-standard database compute credits per equal active minute. Only database compute changes price. Raw CU-second measurements are preserved; mixed or uncertain transition hours waive the premium. Returning to standard restores the effective plan size.", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "environment", "profile", "confirm" ], "properties": { "environment": { "type": "string", "enum": [ "dev", "prod" ] }, "profile": { "type": "string", "enum": [ "standard", "performance" ] }, "confirm": { "type": "boolean", "const": true } } } } } }, "responses": { "202": { "$ref": "#/components/responses/AcceptedOperation" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" }, "get": { "operationId": "getDatabaseCompute", "summary": "Read actual managed database compute configuration", "description": "Project readers can observe current Dev or Prod compute without receiving provider IDs or credentials and without executing SQL or waking the database. Explicitly shared data resolves to the same physical database for both environments. A null database means the owned environment has no confirmed managed placement. Provider failures return a problem, never invented defaults. Configuration describes observed settings, not a completed resize operation. suspend_timeout_seconds is the configured provider value; 0 means provider default and -1 means never suspend.", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "environment", "in": "query", "schema": { "type": "string", "enum": [ "dev", "prod" ], "default": "dev" } } ], "responses": { "200": { "description": "Fresh, tenant-scoped compute observation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseCompute" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/v1/projects/{project_id}/database/write": { "post": { "operationId": "writeProjectDatabase", "summary": "Execute one bounded database write in Dev or Prod", "description": "Owner-authorized INSERT, UPDATE or DELETE through the restricted runtime role, including ordinary upsert. Environment is mandatory. One direct statement and transaction, five-second timeout and at most 1000 directly affected rows; customer triggers and cascades may affect more rows. Rows are not returned. The durable Idempotency-Key receipt persists until project deletion. Same-key retries observe the original execution attempt; unknown outcomes never automatically execute again. Inspect target data before deliberately choosing a new key. Schema changes use GitHub migrations. Database compute is metered normally and existing credit grace and Stop budgets apply. Application row-level security policies remain effective for writes.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDatabaseWriteRequest" } } } }, "responses": { "200": { "description": "Terminal receipt; failed state is not a successful write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDatabaseWriteReceipt" } } } }, "202": { "description": "The same write is in progress. Poll the existing operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDatabaseWriteReceipt" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "402": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/database/query": { "post": { "operationId": "queryProjectDatabase", "summary": "Run one bounded read-only Dev or Prod database query", "description": "Executes one SELECT through the project's least-privilege read-only role. Application row-level security policies apply and may filter rows; a complete SQL archive uses the separate authorized export workflow. Connection credentials are never returned.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDatabaseQueryRequest" } } } }, "responses": { "200": { "description": "At most 100 JSON rows from the selected project database.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDatabaseQueryResult" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/database/access": { "post": { "operationId": "createProjectDatabaseAccess", "summary": "Issue one time-bound PostgreSQL credential for Dev or Prod", "description": "Owner-authorized direct PostgreSQL login for the project's own database, returned exactly once and never retrievable again. Mode read joins the read-only role, mode write joins the same restricted runtime role the application uses; neither can change schema, and application row-level security policies remain effective. The lifetime is 5 minutes to 24 hours (3600 seconds by default) and PostgreSQL refuses new logins after it; the platform ends remaining sessions within 15 minutes after expiry, at the latest. At most three active credentials exist per project environment. Database compute wakes and is metered normally, and existing credit grace and Stop budgets apply. Revoke the credential as soon as the work is finished and never store the connection URI in files, notes or source.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDatabaseAccessRequest" } } } }, "responses": { "201": { "description": "The connection URI is returned once and is never persisted in plaintext.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Pragma": { "schema": { "type": "string", "const": "no-cache" } }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDatabaseAccessCredential" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "402": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" }, "get": { "operationId": "listProjectDatabaseAccess", "summary": "List the project's issued database credentials", "description": "Returns at most the 50 newest credentials with their derived state (active, expired or revoked). Connection URIs and passwords are never returned again; only the credential metadata is readable.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DatabaseEnvironmentFilter" } ], "responses": { "200": { "description": "The newest database credentials for this project, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDatabaseAccessPage" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/database/access/{access_id}": { "delete": { "operationId": "revokeProjectDatabaseAccess", "summary": "Revoke one issued database credential", "description": "Ends the credential's open sessions and removes its PostgreSQL role. Revocation is idempotent for an already revoked credential and never affects the application's own roles or any data.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DatabaseAccessId" } ], "responses": { "200": { "description": "The revoked credential record without any connection URI.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDatabaseAccess" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/deployments/{target_deployment_id}:rollback-plan": { "post": { "operationId": "planDeploymentRollback", "summary": "Plan a deployment rollback", "description": "Produces a non-mutating rollback plan for an immutable deployment artifact.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/TargetDeploymentId" } ], "responses": { "200": { "description": "A rollback plan with a ten-minute action-bound confirmation token.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardedActionPlan" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/deployments/{target_deployment_id}:rollback": { "post": { "operationId": "rollbackDeployment", "summary": "Roll back to an immutable deployment", "description": "Republishes the target deployment artifact without starting a new build.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/TargetDeploymentId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/ConfirmationToken" } ], "responses": { "202": { "$ref": "#/components/responses/AcceptedOperation" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-idempotency": { "canonicalRequestVersion": "v1", "identicalRequest": "replay-stored-response", "changedRequest": "409-idempotency-key-reused" }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/deployments/{source_deployment_id}:promote-plan": { "post": { "operationId": "planDeploymentPromotion", "summary": "Plan promotion of the current dev deployment", "description": "Produces a non-mutating, ten-minute plan that binds the current succeeded dev deployment and current prod head without rebuilding the artifact.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/SourceDeploymentId" } ], "responses": { "200": { "description": "A promotion plan with a ten-minute action-bound confirmation token.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardedActionPlan" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/deployments/{source_deployment_id}:promote": { "post": { "operationId": "promoteDeployment", "summary": "Promote a verified dev artifact to prod", "description": "Activates the immutable artifact from the current succeeded dev deployment in prod without rebuilding it.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/SourceDeploymentId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/ConfirmationToken" } ], "responses": { "202": { "$ref": "#/components/responses/AcceptedOperation" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-idempotency": { "canonicalRequestVersion": "v1", "identicalRequest": "replay-stored-response", "changedRequest": "409-idempotency-key-reused" }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/environments/{environment_id}/secrets": { "get": { "operationId": "listEnvironmentSecrets", "summary": "List environment secret metadata", "description": "Returns names and revisions only. Secret values are never readable through the public API.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "responses": { "200": { "description": "Environment secret metadata ordered by name.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentSecretPage" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/environments/{environment_id}/function-runs": { "get": { "operationId": "listFunctionRuns", "summary": "List the newest scheduled function runs of an environment", "description": "Every declared cron produces one run per due UTC minute; the newest runs come first. A run reports its state, attempt, the status the scheduled handler returned and its timing. Values never include request or response bodies.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "The newest scheduled runs of the environment, newest first.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionRunPage" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/environments/{environment_id}/secrets/{secret_name}": { "put": { "operationId": "putEnvironmentSecret", "summary": "Create or rotate an environment secret", "description": "Accepts a write-only value and returns metadata only. Replays require the same canonical value digest.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/SecretName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutEnvironmentSecretRequest" } } } }, "responses": { "200": { "description": "Stored secret metadata. The value is never returned.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentSecret" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" }, "delete": { "operationId": "deleteEnvironmentSecret", "summary": "Delete an environment secret", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/SecretName" } ], "responses": { "200": { "description": "Idempotent deletion outcome.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteEnvironmentSecretResult" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/operations/{operation_id}": { "get": { "operationId": "getOperation", "summary": "Get an operation", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/OperationId" } ], "responses": { "200": { "description": "The durable operation and its current state.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operation" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/operations/{operation_id}:reconcile": { "post": { "operationId": "reconcileOperation", "summary": "Reconcile an uncertain platform delivery or provider mutation", "description": "Owner-only, idempotent recovery for an operation retained after an uncertain platform delivery or provider mutation. The control plane derives the exact recovery decision, including any deterministic internal Workflow handoff; the request has no body. Exhausted lifecycle recovery returns reconciliation_exhausted (409, retryable false); stop retries and report the original operation through feedback.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OperationId" } ], "responses": { "202": { "description": "The reconciliation attempt was accepted or replayed.", "headers": { "Location": { "description": "Relative URL of the original durable operation resource.", "required": true, "schema": { "type": "string", "pattern": "^/v1/operations/[0-9A-HJKMNP-TV-Z]{26}$" } }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderReconciliationAttempt" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/operations/{operation_id}/events": { "get": { "operationId": "streamOperationEvents", "summary": "Stream operation events", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/OperationId" } ], "responses": { "200": { "description": "A server-sent event stream for the operation.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/OperationEvent" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/audit-events": { "get": { "operationId": "listAuditEvents", "summary": "List audit events", "description": "Returns events visible to the authenticated organization in stable descending order.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectFilter" }, { "$ref": "#/components/parameters/OperationFilter" }, { "$ref": "#/components/parameters/AuditCursor" }, { "$ref": "#/components/parameters/AuditLimit" } ], "responses": { "200": { "description": "One page of visible audit events.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventPage" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-audit-order": [ "occurred_at:desc", "audit_event_id:desc" ], "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/environments/{environment_id}/mail-domain": { "put": { "operationId": "configureManagedMailDomain", "summary": "Configure sending and receiving on a selected mail domain", "description": "One production mail domain per project; environment_id is the project Prod environment ID. Dev and Prod application URLs do not create separate mail domains. Provider credentials never leave ohmyho.st. Content expires 72 hours after original receipt.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "environment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedMailDomainRequest" } } } }, "responses": { "200": { "description": "Authorized mail result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedMailDomain" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" }, "get": { "operationId": "getManagedMailDomain", "summary": "Read independent sending and receiving readiness", "description": "One production mail domain per project; environment_id is the project Prod environment ID. Dev and Prod application URLs do not create separate mail domains. Provider credentials never leave ohmyho.st. Content expires 72 hours after original receipt.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "environment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Authorized mail result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedMailDomain" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" }, "delete": { "operationId": "deleteManagedMailDomain", "summary": "Retire the project's mail domain while the project stays active", "description": "Ends sending and receiving at once, removes the webhook, then removes the domain and its sending key from the mail provider and confirms their absence. DNS is not changed; dns_records lists the records to remove from the domain's DNS, including any that Cloudflare authorization added. Repeat the same idempotency key after an uncertain response. A later mail setup starts a new domain registration.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "environment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "The mail domain is retired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedMailDomainDeleted" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/environments/{environment_id}/mail-webhook": { "put": { "operationId": "prepareManagedMailWebhook", "summary": "Prepare a required customer webhook and return its signing secret", "description": "One production mail domain per project; environment_id is the project Prod environment ID. Dev and Prod application URLs do not create separate mail domains. Provider credentials never leave ohmyho.st. Content expires 72 hours after original receipt.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "environment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedMailWebhookRequest" } } } }, "responses": { "200": { "description": "Authorized mail result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedMailWebhook" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" }, "delete": { "operationId": "disableManagedMailReceiving", "summary": "Disable receiving and remove the customer webhook", "description": "One production mail domain per project; environment_id is the project Prod environment ID. Dev and Prod application URLs do not create separate mail domains. Provider credentials never leave ohmyho.st. Content expires 72 hours after original receipt.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "environment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Authorized mail result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedMailDisabled" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/environments/{environment_id}/mail-webhook/verify": { "post": { "operationId": "verifyManagedMailWebhook", "summary": "Verify the customer endpoint and enable receiving", "description": "One production mail domain per project; environment_id is the project Prod environment ID. Dev and Prod application URLs do not create separate mail domains. Provider credentials never leave ohmyho.st. Content expires 72 hours after original receipt.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "environment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Authorized mail result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedMailDomain" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/environments/{environment_id}/mail/messages": { "get": { "operationId": "listManagedMailMessages", "summary": "List mail handoff metadata within the 72 hour window", "description": "One production mail domain per project; environment_id is the project Prod environment ID. Dev and Prod application URLs do not create separate mail domains. Provider credentials never leave ohmyho.st. Content expires 72 hours after original receipt.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "environment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "after", "in": "query", "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Authorized mail result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedMailMessagePage" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/environments/{environment_id}/mail/messages/{message_id}": { "get": { "operationId": "getManagedMailMessage", "summary": "Retrieve owned mail content before expiry", "description": "One production mail domain per project; environment_id is the project Prod environment ID. Dev and Prod application URLs do not create separate mail domains. Provider credentials never leave ohmyho.st. Content expires 72 hours after original receipt.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "environment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Authorized mail result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedMailContentResult" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/environments/{environment_id}/mail/messages/{message_id}/retry": { "post": { "operationId": "retryManagedMailMessage", "summary": "Retry within the shared maximum of three retries", "description": "One production mail domain per project; environment_id is the project Prod environment ID. Dev and Prod application URLs do not create separate mail domains. Provider credentials never leave ohmyho.st. Content expires 72 hours after original receipt.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "environment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } ], "responses": { "200": { "description": "Authorized mail result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedMailRetryResult" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/environments/{environment_id}/mail/messages/{message_id}/attachments/{attachment_id}": { "get": { "operationId": "getManagedMailAttachment", "summary": "Download an owned attachment before expiry", "description": "One production mail domain per project; environment_id is the project Prod environment ID. Dev and Prod application URLs do not create separate mail domains. Provider credentials never leave ohmyho.st. Content expires 72 hours after original receipt. Downloads over 50 MiB return 413.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "environment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Authorized mail result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedMailExpired" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found" } }, "/v1/projects/{project_id}/data-changes:plan": { "post": { "operationId": "planProjectDataChange", "summary": "Plan a Dev and Prod data assignment change", "description": "Plans one of four Owner-only changes without copying data and issues a ten-minute action-bound confirmation token. shared remains the default at project creation. A Dev reset preserves secrets and access mode and renews a protected share link.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "The data assignment plan and its exact destructive effects.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDataChangePlan" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDataChangeRequest" } } } } } }, "/v1/projects/{project_id}/data-changes": { "post": { "operationId": "createProjectDataChange", "summary": "Execute a confirmed Dev and Prod data assignment change", "description": "Accepts an asynchronous Owner-only data change with the plan ETag, X-Confirmation-Token and Idempotency-Key. It never deletes the data area Prod keeps. Retired Dev resources are removed after access and outstanding upload capabilities are fenced; uncertain effects remain reconcilable.", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/ConfirmationToken" } ], "responses": { "202": { "$ref": "#/components/responses/AcceptedOperation" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }, "x-ohmyhost-idempotency": { "canonicalRequestVersion": "v1", "identicalRequest": "replay-stored-response", "changedRequest": "409-idempotency-key-reused" }, "x-ohmyhost-resource-disclosure": "indistinguishable-not-found", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDataChangeRequest" } } } } } } }, "components": { "headers": { "ETag": { "description": "Opaque version of this response body. Not accepted as If-Match.", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 128 } }, "XRequestId": { "description": "Correlates the request with operations, events, logs, and audit records.", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "parameters": { "AuditCursor": { "name": "cursor", "in": "query", "description": "Opaque continuation cursor returned by the preceding page.", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } }, "AuditLimit": { "name": "limit", "in": "query", "description": "Maximum number of audit events to return.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "Identifies one mutation and its canonical request payload.", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "IfMatch": { "name": "If-Match", "in": "header", "description": "Use resource_etag from a fresh rollback, promotion, deletion or data-change plan. For a project address change, use etag from project status; an ETag from another representation is not accepted.", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 128 } }, "ConfirmationToken": { "name": "X-Confirmation-Token", "in": "header", "description": "Ten-minute token bound to the planned action, project, target resource, and resource ETag.", "required": true, "schema": { "$ref": "#/components/schemas/ConfirmationToken" } }, "RequestId": { "name": "X-Request-Id", "in": "header", "description": "Optional caller-provided correlation identifier.", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "ProjectId": { "name": "project_id", "in": "path", "description": "Project identifier.", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "DatabaseAccessId": { "name": "access_id", "in": "path", "description": "Issued database credential identifier.", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "DatabaseEnvironmentFilter": { "name": "environment", "in": "query", "description": "Restrict the listing to one application environment.", "required": false, "schema": { "type": "string", "enum": [ "dev", "prod" ] } }, "ProjectCursor": { "name": "cursor", "in": "query", "description": "Opaque continuation cursor returned by the preceding project page.", "required": false, "schema": { "$ref": "#/components/schemas/Ulid" } }, "ProjectLimit": { "name": "limit", "in": "query", "description": "Maximum number of projects to return.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "EnvironmentId": { "name": "environment_id", "in": "path", "description": "Environment identifier.", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "SecretName": { "name": "secret_name", "in": "path", "description": "Uppercase environment-variable name.", "required": true, "schema": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,127}$" } }, "FeedbackId": { "name": "feedback_id", "in": "path", "description": "Feedback receipt identifier returned on submission.", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "OperationId": { "name": "operation_id", "in": "path", "description": "Operation identifier.", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "DeploymentId": { "name": "deployment_id", "in": "path", "description": "Deployment identifier.", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "TargetDeploymentId": { "name": "target_deployment_id", "in": "path", "description": "Immutable deployment selected as the rollback target.", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "SourceDeploymentId": { "name": "source_deployment_id", "in": "path", "required": true, "description": "Current succeeded dev deployment whose immutable artifact will be promoted.", "schema": { "$ref": "#/components/schemas/Ulid" } }, "DeploymentCursor": { "name": "cursor", "in": "query", "description": "Opaque continuation cursor returned by the preceding deployment page.", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } }, "DeploymentLimit": { "name": "limit", "in": "query", "description": "Maximum number of deployments to return.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "ProjectFilter": { "name": "project_id", "in": "query", "description": "Restricts the page to one visible project.", "required": false, "schema": { "$ref": "#/components/schemas/Ulid" } }, "OperationFilter": { "name": "operation_id", "in": "query", "description": "Restricts the page to one visible operation.", "required": false, "schema": { "$ref": "#/components/schemas/Ulid" } } }, "responses": { "AcceptedOperation": { "description": "The mutation was accepted for asynchronous processing.", "headers": { "Location": { "description": "Relative URL of the durable operation resource.", "required": true, "schema": { "type": "string", "pattern": "^/v1/operations/[0-9A-HJKMNP-TV-Z]{26}$" } }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operation" } } } }, "Problem": { "description": "The request failed.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ResourceNotFound": { "description": "The resource does not exist or is not visible to the authenticated principal.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resourceNotFound": { "value": { "type": "https://docs.ohmyho.st/errors/resource-not-found", "title": "Resource not found", "status": 404, "code": "resource_not_found", "request_id": "req_01J00000000000000000000000", "retryable": false, "suggested_action": "Check the resource identifier and your access scope." } } } } } }, "IdempotencyConflict": { "description": "The idempotency key was already used with a different canonical request.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/IdempotencyConflictProblem" }, "examples": { "reusedKey": { "value": { "type": "https://docs.ohmyho.st/errors/idempotency-key-reused", "title": "Idempotency key reused", "status": 409, "code": "idempotency_key_reused", "request_id": "req_01J00000000000000000000000", "retryable": false, "suggested_action": "Retry with a new idempotency key." } } } } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "WorkOS access JWT or a user-owned WorkOS API key. User keys are bound to one organization and restricted to their enabled product permissions. Session-only onboarding and session revocation require an interactive access JWT. No cookie session is assumed." } }, "schemas": { "ManagedMailDomainRequest": { "type": "object", "additionalProperties": false, "required": [ "domain", "sending", "receiving" ], "properties": { "domain": { "type": "string", "minLength": 4, "maxLength": 253 }, "sending": { "type": "boolean" }, "receiving": { "type": "boolean" } } }, "ManagedMailWebhookRequest": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 } } }, "ManagedMailDnsRecord": { "type": "object", "additionalProperties": false, "required": [ "type", "name", "value", "purpose", "status" ], "properties": { "type": { "type": "string", "enum": [ "TXT", "CNAME", "MX" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "integer", "minimum": 0, "maximum": 65535 } } }, "ManagedMailDomain": { "type": "object", "additionalProperties": false, "required": [ "domain_id", "domain", "environment_id", "sending", "receiving", "status", "configured_at", "observed_at", "dns_records", "webhook", "next_check_after_seconds" ], "properties": { "domain_id": { "$ref": "#/components/schemas/Ulid" }, "domain": { "type": "string" }, "environment_id": { "$ref": "#/components/schemas/Ulid" }, "sending": { "type": "string", "enum": [ "disabled", "pending", "ready", "failed" ] }, "receiving": { "type": "string", "enum": [ "disabled", "pending", "ready", "failed" ] }, "status": { "type": "string", "enum": [ "ready", "verification_pending" ] }, "configured_at": { "type": "string", "format": "date-time" }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "dns_records": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedMailDnsRecord" } }, "dns": { "type": "object", "additionalProperties": false, "required": [ "status", "records" ], "properties": { "status": { "type": "string", "enum": [ "configured", "action_required", "conflict" ] }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedMailDnsRecord" } } } }, "webhook": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "url", "verified" ], "properties": { "url": { "type": "string", "format": "uri" }, "verified": { "type": "boolean" } } }, "next_check_after_seconds": { "type": [ "integer", "null" ], "enum": [ 60, null ] } } }, "ManagedMailWebhook": { "type": "object", "additionalProperties": false, "required": [ "url", "signing_secret", "status" ], "properties": { "url": { "type": "string", "format": "uri" }, "signing_secret": { "type": "string", "description": "Server-only signing secret. Never log or send it to the browser." }, "status": { "type": "string", "const": "verification_required" } } }, "ManagedMailDisabled": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "const": "disabled" } } }, "ManagedMailDomainDeleted": { "type": "object", "additionalProperties": false, "required": [ "status", "domain", "dns_records" ], "properties": { "status": { "type": "string", "const": "deleted" }, "domain": { "type": "string" }, "dns_records": { "type": "array", "description": "Records ohmyho.st no longer manages; remove them from the domain's DNS.", "items": { "$ref": "#/components/schemas/ManagedMailDnsRecord" } } } }, "ManagedMailExpired": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "const": "expired" } } }, "ManagedMailRetryResult": { "type": "object", "additionalProperties": false, "required": [ "attempted" ], "properties": { "attempted": { "type": "boolean" }, "delivered": { "type": "boolean" } } }, "ManagedMailMessagePage": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "message_id", "received_at", "state", "attempts" ], "properties": { "message_id": { "$ref": "#/components/schemas/Ulid" }, "received_at": { "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "pending", "delivering", "delivered", "delivery_failed", "expired" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 4 } } } } } }, "ManagedMailContentResult": { "oneOf": [ { "$ref": "#/components/schemas/ManagedMailExpired" }, { "$ref": "#/components/schemas/ManagedMailContent" } ] }, "ManagedMailContent": { "type": "object", "additionalProperties": false, "required": [ "id", "domain", "received_at", "expires_at", "from", "to", "subject", "text", "html", "message_id", "attachments" ], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "domain": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "text": { "type": [ "string", "null" ] }, "html": { "type": [ "string", "null" ] }, "message_id": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "filename", "content_type", "download_path" ], "properties": { "id": { "type": "string" }, "filename": { "type": [ "string", "null" ] }, "content_type": { "type": "string" }, "download_path": { "type": "string" } } } } } }, "FeatureVoteChoices": { "type": "array", "minItems": 3, "maxItems": 3, "description": "One entry for each roadmap topic; no personal data or other browsers' votes.", "items": { "type": "object", "additionalProperties": false, "required": [ "feature", "choice" ], "properties": { "feature": { "type": "string", "enum": [ "eu", "iso27001", "soc2" ] }, "choice": { "type": [ "string", "null" ], "enum": [ "up", "down", null ] } } } }, "FeatureVoteState": { "type": "object", "additionalProperties": false, "required": [ "votes" ], "properties": { "votes": { "$ref": "#/components/schemas/FeatureVoteChoices" } } }, "UserApiKeyId": { "type": "string", "pattern": "^api_key_[A-Za-z0-9_]{1,120}$" }, "UserApiKey": { "type": "object", "additionalProperties": false, "required": [ "id", "organization_id", "name", "obfuscated_value", "permissions", "expires_at", "created_at", "last_used_at" ], "properties": { "id": { "$ref": "#/components/schemas/UserApiKeyId" }, "organization_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "obfuscated_value": { "type": "string", "pattern": "^sk_(?:\\.\\.\\.|…)[A-Za-z0-9_-]{1,12}$" }, "permissions": { "type": "array", "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9_.*:-]{1,128}$" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "UserApiKeyCreation": { "type": "object", "additionalProperties": false, "required": [ "request_id", "replayed", "key", "value" ], "properties": { "request_id": { "$ref": "#/components/schemas/Ulid" }, "replayed": { "type": "boolean" }, "key": { "$ref": "#/components/schemas/UserApiKey" }, "value": { "type": [ "string", "null" ], "pattern": "^sk_[A-Za-z0-9_-]{20,128}$" } }, "oneOf": [ { "properties": { "replayed": { "const": false }, "value": { "type": "string" } } }, { "properties": { "replayed": { "const": true }, "value": { "type": "null" } } } ] }, "UserApiKeyPage": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/UserApiKey" } }, "next_cursor": { "type": [ "string", "null" ], "pattern": "^api_key_[A-Za-z0-9_]{1,120}$" } } }, "CreditMicros": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "description": "Non-negative microcredits, at most 9223372036854775807. One credit equals 1000000 microcredits." }, "BillingTaxIssue": { "description": "Verified issue on an existing Stripe invoice; no new purchase is needed.", "type": [ "object", "null" ], "additionalProperties": false, "required": [ "code", "invoice_id", "observed_at", "required_action" ], "properties": { "code": { "type": "string", "enum": [ "billing_tax_location_required", "billing_tax_calculation_failed", "billing_tax_configuration_required" ] }, "invoice_id": { "type": "string", "pattern": "^in_[A-Za-z0-9_]{1,253}$" }, "observed_at": { "type": "string", "format": "date-time" }, "required_action": { "type": "string", "enum": [ "open_billing_portal", "contact_support" ] } } }, "BillingRecharge": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "portal_available", "enabled", "revision", "status", "monthly_limit_minor", "spent_minor", "currency", "amount_minor", "credits", "threshold_credits", "setup_url", "invoice_url", "billing_issue" ], "properties": { "organization_id": { "$ref": "#/components/schemas/Ulid" }, "portal_available": { "type": "boolean", "description": "An existing customer in this billing account is ready for a hosted billing-portal handoff; this does not imply a paid subscription." }, "enabled": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "off", "setup_required", "on", "payment_required", "monthly_limit", "needs_reconciliation", "tax_required" ] }, "monthly_limit_minor": { "type": "integer", "minimum": 1000, "maximum": 100000 }, "spent_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "const": "usd" }, "amount_minor": { "type": "integer", "const": 900 }, "credits": { "type": "integer", "const": 1000 }, "threshold_credits": { "type": "integer", "const": 100 }, "setup_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 8192 }, "invoice_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 8192 }, "billing_issue": { "$ref": "#/components/schemas/BillingTaxIssue" } } }, "BillingCheckout": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "checkout_id", "offer", "state", "payment_confirmed", "url", "expires_at", "packs", "credited_micros", "revoked_micros", "paid_until", "required_action", "billing_issue" ], "properties": { "organization_id": { "$ref": "#/components/schemas/Ulid" }, "checkout_id": { "$ref": "#/components/schemas/Ulid" }, "offer": { "type": "string", "enum": [ "topup", "paid" ] }, "state": { "type": "string", "enum": [ "open", "complete", "expired" ] }, "payment_confirmed": { "type": "boolean" }, "url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 8192 }, "expires_at": { "type": "string", "format": "date-time" }, "packs": { "type": "integer", "minimum": 1, "maximum": 100 }, "credited_micros": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$" }, "revoked_micros": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$" }, "paid_until": { "type": [ "string", "null" ], "format": "date-time" }, "required_action": { "type": "string", "enum": [ "none", "complete_checkout", "open_billing_portal", "contact_support" ], "description": "Human payment handoff. Complete the returned Checkout URL, request a fresh billing portal URL to correct billing details, or contact ohmyho.st when tax configuration requires review. none includes a draft invoice awaiting automatic processing; it is not a claim of current Paid coverage. Never infer renewal success from the historical payment_confirmed flag." }, "billing_issue": { "$ref": "#/components/schemas/BillingTaxIssue" } } }, "BillingPortal": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "url", "created_at" ], "properties": { "organization_id": { "$ref": "#/components/schemas/Ulid" }, "url": { "type": "string", "format": "uri", "maxLength": 8192 }, "created_at": { "type": "string", "format": "date-time" } } }, "OrganizationCredits": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "unit", "as_of", "available_micros", "reserved_micros", "spent_micros", "expired_micros", "platform_overrun_micros", "grace_started_at", "grace_expires_at", "active_meters", "rate_cards" ], "properties": { "organization_id": { "$ref": "#/components/schemas/Ulid" }, "unit": { "type": "string", "const": "microcredits" }, "as_of": { "type": "string", "format": "date-time" }, "available_micros": { "$ref": "#/components/schemas/CreditMicros" }, "reserved_micros": { "$ref": "#/components/schemas/CreditMicros" }, "spent_micros": { "$ref": "#/components/schemas/CreditMicros" }, "expired_micros": { "$ref": "#/components/schemas/CreditMicros" }, "platform_overrun_micros": { "$ref": "#/components/schemas/CreditMicros" }, "grace_started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "First confirmed exhaustion in this continuous period; null while funded." }, "grace_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Seven days after first confirmed exhaustion. Existing services and domains are retained during this grace; no automatic data deletion. Explicit project stop budgets are separate." }, "active_meters": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9_.-]{1,128}$" } }, "rate_cards": { "type": "array", "maxItems": 4, "description": "Published integer prices, newest first. A published rate is not proof of enabled billing; only active_meters names currently billed sources. Builds retain their accepted quote. Provider cost is a list-price basis before platform allowances, not an invoice.", "items": { "$ref": "#/components/schemas/PublishedCreditRateCard" } } } }, "UsageTotal": { "type": "string", "description": "Non-negative integer aggregate, serialized exactly without floating-point rounding.", "pattern": "^(0|[1-9][0-9]{0,37})$" }, "OrganizationCreditUsage": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "month", "as_of", "unit", "data", "next_cursor" ], "properties": { "organization_id": { "$ref": "#/components/schemas/Ulid" }, "month": { "type": "string", "pattern": "^20[0-9]{2}-(0[1-9]|1[0-2])$" }, "as_of": { "type": "string", "format": "date-time" }, "unit": { "type": "string", "const": "microcredits" }, "next_cursor": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "data": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "project_id", "reserved_micros", "meters" ], "properties": { "project_id": { "$ref": "#/components/schemas/Ulid" }, "reserved_micros": { "$ref": "#/components/schemas/UsageTotal" }, "meters": { "type": "array", "maxItems": 1000, "items": { "type": "object", "additionalProperties": false, "required": [ "environment_id", "meter", "unit", "rate_card_id", "quantity", "charged_micros", "funded_micros", "platform_overrun_micros" ], "properties": { "environment_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "meter": { "type": "string", "pattern": "^[A-Za-z0-9_.:/-]{1,128}$" }, "unit": { "type": "string", "pattern": "^[A-Za-z0-9_.:/-]{1,128}$" }, "rate_card_id": { "type": "string", "pattern": "^[A-Za-z0-9_.:/-]{1,128}$" }, "quantity": { "$ref": "#/components/schemas/UsageTotal" }, "charged_micros": { "$ref": "#/components/schemas/UsageTotal" }, "funded_micros": { "$ref": "#/components/schemas/UsageTotal" }, "platform_overrun_micros": { "$ref": "#/components/schemas/UsageTotal" } } } } } } } } }, "PublishedCreditRateCard": { "type": "object", "additionalProperties": false, "required": [ "id", "currency", "published_at", "effective_from", "rates" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_.-]{1,128}$" }, "currency": { "type": "string", "const": "USD" }, "published_at": { "type": "string", "format": "date-time" }, "effective_from": { "type": "string", "format": "date-time" }, "rates": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "meter", "unit", "units_per_charge", "provider_cost_micros", "credit_micros" ], "properties": { "meter": { "type": "string", "pattern": "^[a-z0-9_.-]{1,128}$" }, "unit": { "type": "string", "pattern": "^[a-z0-9_.-]{1,128}$" }, "units_per_charge": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "provider_cost_micros": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "description": "Provider list-cost basis for units_per_charge, in USD micro-units (1000000 equals 1 USD), before shared allowances and discounts." }, "credit_micros": { "$ref": "#/components/schemas/CreditMicros" } } } } } }, "SetProjectCreditBudgetRequest": { "type": "object", "additionalProperties": false, "required": [ "amount_micros", "mode" ], "properties": { "amount_micros": { "oneOf": [ { "$ref": "#/components/schemas/CreditMicros" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "continue", "stop" ] } } }, "ProjectCreditBudget": { "type": "object", "additionalProperties": false, "required": [ "project_id", "amount_micros", "mode", "used_micros", "reserved_micros", "period_start", "period_end", "as_of" ], "properties": { "project_id": { "$ref": "#/components/schemas/Ulid" }, "amount_micros": { "oneOf": [ { "$ref": "#/components/schemas/CreditMicros" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "continue", "stop" ] }, "used_micros": { "$ref": "#/components/schemas/CreditMicros" }, "reserved_micros": { "$ref": "#/components/schemas/CreditMicros" }, "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "as_of": { "type": "string", "format": "date-time" } } }, "CreateCloudflareDnsAuthorizationRequest": { "type": "object", "additionalProperties": false, "required": [ "zone" ], "properties": { "zone": { "type": "string", "minLength": 4, "maxLength": 253, "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$" } } }, "CloudflareDnsAuthorization": { "type": "object", "description": "Short-lived credential-free redirect information for one Cloudflare OAuth authorization.", "additionalProperties": false, "required": [ "authorization_id", "authorization_url", "expires_at" ], "properties": { "authorization_id": { "$ref": "#/components/schemas/Ulid" }, "authorization_url": { "type": "string", "format": "uri", "minLength": 20, "maxLength": 4096, "pattern": "^https://dash\\.cloudflare\\.com/oauth2/auth\\?" }, "expires_at": { "type": "string", "format": "date-time" } } }, "CloudflareDnsAuthorizationStatus": { "type": "object", "description": "Credential-free project authorization state. Without an authorization, status is not_authorized, zone and expires_at are null, and scopes is empty. All other states name the actual customer zone; no platform or customer zone is inferred.", "additionalProperties": false, "required": [ "status", "zone", "scopes", "expires_at" ], "properties": { "status": { "type": "string", "enum": [ "not_authorized", "pending", "authorized", "expired", "revoked" ] }, "zone": { "type": [ "string", "null" ], "minLength": 4, "maxLength": 253, "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$" }, "scopes": { "type": "array", "uniqueItems": true, "maxItems": 2, "items": { "type": "string", "enum": [ "dns.write", "zone.read" ] } }, "expires_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "PaidDomainRequest": { "type": "object", "additionalProperties": false, "required": [ "hostname" ], "properties": { "hostname": { "type": "string", "minLength": 4, "maxLength": 253, "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$" } } }, "PaidDomainPlan": { "type": "object", "additionalProperties": false, "required": [ "status", "hostname", "environment", "cname_target", "effects", "risks" ], "properties": { "status": { "type": "string", "const": "planned" }, "hostname": { "type": "string", "minLength": 4, "maxLength": 253 }, "environment": { "type": "string", "const": "prod" }, "cname_target": { "type": "string", "enum": [ "customers.omh.st", "customers.ohmyho.st" ] }, "effects": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "string", "minLength": 1, "maxLength": 512 } }, "risks": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "string", "minLength": 1, "maxLength": 512 } } } }, "PaidDomain": { "type": "object", "description": "awaiting_deployment means the requested hostname is declared but not provisioned. Its hostname is present, suspension_reason, custom_hostname_status, ssl_status and url are null, and validation_records is empty. Authorize Cloudflare, deploy to Prod, then repeat the same apply.", "additionalProperties": false, "required": [ "status", "suspension_reason", "hostname", "environment", "cname_target", "custom_hostname_status", "ssl_status", "validation_records", "url" ], "properties": { "status": { "type": "string", "enum": [ "not_configured", "awaiting_deployment", "pending", "active", "reconciliation_required", "deleted", "suspended" ] }, "suspension_reason": { "type": [ "string", "null" ], "enum": [ "paid_plan_required", "insufficient_organization_credits", "project_budget_exceeded", null ], "description": "Non-null only while suspended by the same Paid, credit-grace or stop-budget policy used by the gateway. DNS/TLS receipts remain intact; url is null while suspended." }, "hostname": { "oneOf": [ { "type": "string", "minLength": 4, "maxLength": 253 }, { "type": "null" } ] }, "environment": { "type": "string", "const": "prod" }, "cname_target": { "type": "string", "enum": [ "customers.omh.st", "customers.ohmyho.st" ] }, "custom_hostname_status": { "type": [ "string", "null" ] }, "ssl_status": { "type": [ "string", "null" ] }, "validation_records": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": [ "type", "name", "content", "purpose" ], "properties": { "type": { "type": "string", "enum": [ "CNAME", "TXT" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 253 }, "content": { "type": "string", "minLength": 1, "maxLength": 2048 }, "purpose": { "type": "string", "enum": [ "traffic", "ownership", "ssl", "dcv_delegation" ] } } } }, "url": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^https://" }, { "type": "null" } ] } } }, "PutEnvironmentSecretRequest": { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "string", "description": "Write-only plaintext value. It is encrypted before persistence and never returned.", "minLength": 1, "maxLength": 5120, "writeOnly": true } } }, "EnvironmentSecret": { "type": "object", "description": "Environment secret metadata. The plaintext and ciphertext are never returned.", "additionalProperties": false, "required": [ "name", "revision", "key_version", "created_at", "updated_at", "desired_generation", "applied_generation", "delivery_state", "runtime_provider", "applied_secret_count", "last_error" ], "properties": { "name": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,127}$" }, "revision": { "type": "integer", "minimum": 1 }, "key_version": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "desired_generation": { "type": "integer", "minimum": 0 }, "applied_generation": { "type": "integer", "minimum": 0 }, "delivery_state": { "type": "string", "enum": [ "not_deployed", "pending", "ready", "failed" ] }, "runtime_provider": { "type": [ "string", "null" ], "enum": [ "wfp", null ] }, "applied_secret_count": { "type": "integer", "minimum": 0, "maximum": 100 }, "last_error": { "type": [ "string", "null" ], "pattern": "^[A-Z][A-Z0-9_]{0,63}$" } } }, "EnvironmentSecretPage": { "type": "object", "additionalProperties": false, "required": [ "items", "desired_generation", "applied_generation", "delivery_state", "runtime_provider", "applied_secret_count", "last_error" ], "properties": { "items": { "type": "array", "maxItems": 256, "items": { "$ref": "#/components/schemas/EnvironmentSecret" } }, "desired_generation": { "type": "integer", "minimum": 0 }, "applied_generation": { "type": "integer", "minimum": 0 }, "delivery_state": { "type": "string", "enum": [ "not_deployed", "pending", "ready", "failed" ] }, "runtime_provider": { "type": [ "string", "null" ], "enum": [ "wfp", null ] }, "applied_secret_count": { "type": "integer", "minimum": 0, "maximum": 100 }, "last_error": { "type": [ "string", "null" ], "pattern": "^[A-Z][A-Z0-9_]{0,63}$" } } }, "DeleteEnvironmentSecretResult": { "type": "object", "additionalProperties": false, "required": [ "name", "status", "desired_generation", "applied_generation", "delivery_state", "runtime_provider", "applied_secret_count", "last_error" ], "properties": { "name": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,127}$" }, "status": { "type": "string", "enum": [ "deleted", "absent" ] }, "desired_generation": { "type": "integer", "minimum": 0 }, "applied_generation": { "type": "integer", "minimum": 0 }, "delivery_state": { "type": "string", "enum": [ "not_deployed", "pending", "ready", "failed" ] }, "runtime_provider": { "type": [ "string", "null" ], "enum": [ "wfp", null ] }, "applied_secret_count": { "type": "integer", "minimum": 0, "maximum": 100 }, "last_error": { "type": [ "string", "null" ], "pattern": "^[A-Z][A-Z0-9_]{0,63}$" } } }, "LinkProjectSourceRequest": { "type": "object", "additionalProperties": false, "required": [ "repository_owner", "repository_name" ], "properties": { "repository_owner": { "type": "string", "minLength": 1, "maxLength": 39, "pattern": "^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$" }, "repository_name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._-]+$" } } }, "ConfigureSourceAutoDeployRequest": { "type": "object", "additionalProperties": false, "required": [ "branch", "enabled" ], "properties": { "branch": { "type": "string", "description": "Exact Git branch accepted by Git check-ref-format branch rules; control/space, dot-lock, reflog, range and metacharacter forms are rejected.", "minLength": 1, "maxLength": 1024, "pattern": "^(?!.*(?:\\.\\.|@\\{|//|\\\\|[~^:?*\\[\\]\\x00-\\x20\\x7f]))(?!.*(?:^|/)\\.)(?!.*(?:^|/)[^/]*\\.lock(?:/|$))(?!.*\\.$)[A-Za-z0-9][A-Za-z0-9._/-]{0,1023}$" }, "enabled": { "type": "boolean" } } }, "SourceAutoDeploy": { "type": "object", "additionalProperties": false, "description": "Push-to-deploy configuration. Generation 0 with null branch, ref, grant_status and updated_at means auto-deploy was never configured for this project.", "required": [ "branch", "ref", "environment", "enabled", "generation", "grant_status", "updated_at" ], "properties": { "branch": { "type": [ "string", "null" ] }, "ref": { "type": [ "string", "null" ], "pattern": "^refs/heads/" }, "environment": { "type": "string", "enum": [ "dev" ] }, "enabled": { "type": "boolean" }, "generation": { "type": "integer", "minimum": 0 }, "grant_status": { "type": [ "string", "null" ], "enum": [ "active", "revoked", null ] }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ConnectGithubOrganizationRequest": { "type": "object", "additionalProperties": false }, "GithubOrganizationConnection": { "type": "object", "additionalProperties": false, "required": [ "connection_id", "organization_id", "installation_id", "account_id", "account_login", "account_type", "github_user_id", "github_user_login", "connected_at", "revoked_at", "settings_url" ], "properties": { "connection_id": { "$ref": "#/components/schemas/Ulid" }, "organization_id": { "$ref": "#/components/schemas/Ulid" }, "installation_id": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "account_id": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "account_login": { "type": "string", "minLength": 1, "maxLength": 39 }, "account_type": { "type": "string", "enum": [ "User", "Organization" ] }, "github_user_id": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "github_user_login": { "type": "string", "minLength": 1, "maxLength": 39 }, "connected_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "settings_url": { "type": "string", "format": "uri" } } }, "GithubOrganizationConnectionStatus": { "type": "object", "additionalProperties": false, "required": [ "status", "connection" ], "properties": { "status": { "type": "string", "enum": [ "not_connected", "connected", "revoked" ] }, "connection": { "oneOf": [ { "$ref": "#/components/schemas/GithubOrganizationConnection" }, { "type": "null" } ] } } }, "GithubConnectionAuthorization": { "type": "object", "additionalProperties": false, "required": [ "authorization_id", "status", "last_failure", "authorization_url", "expires_at", "connection" ], "properties": { "authorization_id": { "type": [ "string", "null" ], "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "status": { "type": "string", "enum": [ "pending", "authorizing", "connected", "failed", "expired" ] }, "last_failure": { "type": [ "string", "null" ], "enum": [ "installation_access_required", "account_admin_required", "authorization_code_rejected", "provider_unavailable", "expired", "session_inactive", "denied", "code_spent", "state_unknown", null ] }, "authorization_url": { "type": [ "string", "null" ], "format": "uri", "description": "One GitHub browser authorization link when pending; contains only the bound single-use state, never a provider credential." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "connection": { "oneOf": [ { "$ref": "#/components/schemas/GithubOrganizationConnection" }, { "type": "null" } ] } } }, "GithubSourceAuthorization": { "type": "object", "additionalProperties": false, "required": [ "authorization_id", "status", "last_failure", "authorization_url", "installation_url", "expires_at", "operation_id", "installation_id", "repository_id", "repository_owner", "repository_name" ], "properties": { "authorization_id": { "$ref": "#/components/schemas/Ulid" }, "status": { "type": "string", "enum": [ "pending", "authorizing", "authorized", "failed", "expired" ] }, "last_failure": { "type": [ "string", "null" ], "description": "Why the last callback did not finish. A pending authorization that carries one is resumable; resolve the named cause, then open authorization_url again without a new key.", "enum": [ "repository_not_installed", "repository_access_required", "authorization_code_rejected", "provider_unavailable", "expired", "session_inactive", "denied", "code_spent", null ] }, "authorization_url": { "type": [ "string", "null" ], "format": "uri", "description": "Open only when pending; contains the single-use state and PKCE challenge, never a provider credential." }, "installation_url": { "type": [ "string", "null" ], "format": "uri", "description": "Install or update the GitHub App's selected repository access before authorizing, if required." }, "expires_at": { "type": "string", "format": "date-time" }, "operation_id": { "type": [ "string", "null" ], "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "installation_id": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" }, "repository_id": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" }, "repository_owner": { "type": "string" }, "repository_name": { "type": "string" } } }, "ProjectSource": { "type": "object", "additionalProperties": false, "required": [ "provider", "installation_id", "repository_full_name", "status", "linked_at", "updated_at" ], "properties": { "provider": { "type": "string", "const": "github" }, "installation_id": { "type": "string", "pattern": "^[1-9][0-9]*$", "maxLength": 20 }, "repository_full_name": { "type": "string", "minLength": 3, "maxLength": 201, "pattern": "^[^/]+/[^/]+$" }, "status": { "type": "string", "enum": [ "pending", "ready", "failed", "revoked" ] }, "linked_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "failure_summary": { "type": "string", "minLength": 1, "maxLength": 512 } } }, "FunctionRun": { "type": "object", "additionalProperties": false, "required": [ "id", "deployment_id", "cron", "scheduled_at", "state", "attempt", "status_code", "started_at", "finished_at" ], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "deployment_id": { "$ref": "#/components/schemas/Ulid" }, "cron": { "type": "string", "maxLength": 64 }, "scheduled_at": { "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "due", "running", "retry", "succeeded", "failed" ] }, "attempt": { "type": "integer", "minimum": 0, "maximum": 3 }, "status_code": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599 }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "FunctionRunPage": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/FunctionRun" } } } }, "DeploymentDiagnostic": { "type": "object", "additionalProperties": false, "required": [ "id", "source", "code", "message", "occurred_at" ], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "source": { "type": "string", "enum": [ "build", "control", "runtime", "function" ] }, "code": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{1,63}$" }, "message": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{1,127}$" }, "exception_class": { "type": "string", "maxLength": 128 }, "file": { "type": "string", "maxLength": 512 }, "line": { "type": "integer", "minimum": 1 }, "column": { "type": "integer", "minimum": 0 }, "route": { "type": "string", "maxLength": 512 }, "request_id": { "type": "string", "maxLength": 128 }, "trace_id": { "type": "string", "maxLength": 128 }, "duration_ms": { "type": "integer", "minimum": 0, "maximum": 900000 }, "excerpt": { "type": "string", "minLength": 1, "maxLength": 16384, "description": "The customer's own output with control characters removed before storage: on BUILD_FAILED the tail of the install/build output (newest lines last), on HEALTH_CHECK_FAILED the head of the body the health check was answered with (at most 4096 characters, never a header). A running application holds its environment's secrets and this answer is not scanned for them, so, like a query of the project's database, a HEALTH_CHECK_FAILED excerpt is returned only to an owner of the project; never answer a health check with a secret." }, "excerpt_truncated": { "type": "boolean", "description": "Whether output was omitted from excerpt (earlier build output, or the rest of the health answer). Present exactly when excerpt is present." }, "status_code": { "type": "integer", "minimum": 100, "maximum": 599, "description": "The HTTP status the health check was answered with; present only on HEALTH_CHECK_FAILED. The probe is a cookieless GET of route that follows no redirect, so a 3xx is unhealthy too." }, "occurred_at": { "type": "string", "format": "date-time" } } }, "DeploymentDiagnosticPage": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/DeploymentDiagnostic" } }, "next_cursor": { "type": "string", "maxLength": 2048 } } }, "ProjectDatabaseWriteRequest": { "type": "object", "additionalProperties": false, "required": [ "environment", "statement", "parameters" ], "properties": { "environment": { "type": "string", "enum": [ "dev", "prod" ] }, "statement": { "type": "string", "minLength": 1, "maxLength": 65536, "description": "One direct INSERT, UPDATE or DELETE, max 64 KiB UTF-8; entire JSON request is limited to 65,600 bytes." }, "parameters": { "type": "array", "maxItems": 100, "items": {}, "description": "JSON values, at most 8 levels and 10000 nodes, max 64 KiB encoded." } } }, "ProjectDatabaseWriteReceipt": { "type": "object", "additionalProperties": false, "required": [ "operation_id", "environment", "state", "command", "affected_rows", "error" ], "properties": { "operation_id": { "$ref": "#/components/schemas/Ulid" }, "environment": { "type": "string", "enum": [ "dev", "prod" ] }, "state": { "type": "string", "enum": [ "running", "succeeded", "failed" ] }, "command": { "type": [ "string", "null" ], "enum": [ "INSERT", "UPDATE", "DELETE", null ] }, "affected_rows": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000 }, "error": { "oneOf": [ { "$ref": "#/components/schemas/OperationFailure" }, { "type": "null" } ] } } }, "ProjectDatabaseQueryRequest": { "type": "object", "additionalProperties": false, "required": [ "environment", "statement", "parameters" ], "properties": { "environment": { "type": "string", "enum": [ "dev", "prod" ] }, "statement": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^\\s*(?:SELECT|WITH)\\b" }, "parameters": { "type": "array", "maxItems": 32, "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } } }, "ProjectDatabaseQueryResult": { "type": "object", "additionalProperties": false, "required": [ "environment", "rows", "row_count", "truncated" ], "properties": { "environment": { "type": "string", "enum": [ "dev", "prod" ] }, "rows": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": true } }, "row_count": { "type": "integer", "minimum": 0, "maximum": 100 }, "truncated": { "type": "boolean" } } }, "ProjectDatabaseAccessRequest": { "type": "object", "additionalProperties": false, "required": [ "environment" ], "properties": { "environment": { "type": "string", "enum": [ "dev", "prod" ] }, "mode": { "type": "string", "enum": [ "read", "write" ], "default": "read", "description": "read joins the read-only role; write joins the restricted runtime role. Neither can change schema." }, "ttl_seconds": { "type": "integer", "minimum": 300, "maximum": 86400, "default": 3600, "description": "Credential lifetime between 5 minutes and 24 hours." }, "label": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 64, "description": "Optional customer label without control characters or surrounding whitespace." } } }, "ProjectDatabaseAccess": { "type": "object", "additionalProperties": false, "required": [ "access_id", "environment", "mode", "role_name", "host", "database", "label", "state", "issued_at", "expires_at", "revoked_at", "revocation_reason" ], "properties": { "access_id": { "$ref": "#/components/schemas/Ulid" }, "environment": { "type": "string", "enum": [ "dev", "prod" ] }, "mode": { "type": "string", "enum": [ "read", "write" ] }, "role_name": { "type": "string", "pattern": "^ohmyho_da_[0-7][0-9a-hjkmnp-tv-z]{25}_[0-9a-z]{8}$" }, "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "database": { "type": "string", "const": "neondb" }, "label": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 64 }, "state": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "issued_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "revocation_reason": { "type": [ "string", "null" ], "enum": [ "principal", "expired", "budget", "creation_failed", "data_change", null ] } } }, "ProjectDatabaseAccessCredential": { "allOf": [ { "$ref": "#/components/schemas/ProjectDatabaseAccess" }, { "type": "object", "additionalProperties": false, "required": [ "connection_uri", "psql_command" ], "properties": { "connection_uri": { "type": "string", "format": "uri", "description": "Returned exactly once. Use it immediately and never store it in files, notes or source." }, "psql_command": { "type": "string", "description": "The same credential as a ready psql invocation." } } } ] }, "ProjectDatabaseAccessPage": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/ProjectDatabaseAccess" } } } }, "SetDevAccessModeRequest": { "type": "object", "additionalProperties": false, "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "protected", "public" ] } } }, "OrganizationReferral": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "referral_url" ], "properties": { "organization_id": { "$ref": "#/components/schemas/Ulid" }, "referral_url": { "type": "string", "format": "uri", "pattern": "^https://ohmyho\\.st/\\?r=ref-[0-7][0-9a-hjkmnp-tv-z]{25}$" } } }, "SetPoweredByFlagRequest": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, "PoweredByFlag": { "type": "object", "additionalProperties": false, "required": [ "project_id", "enabled", "enabled_at" ], "properties": { "project_id": { "$ref": "#/components/schemas/Ulid" }, "enabled": { "type": "boolean" }, "enabled_at": { "description": "When the current owner switched the flag on; null while it is hidden.", "type": [ "string", "null" ], "format": "date-time" } } }, "DevAccessState": { "type": "object", "additionalProperties": false, "required": [ "project_id", "mode", "share_url" ], "properties": { "project_id": { "$ref": "#/components/schemas/Ulid" }, "mode": { "type": "string", "enum": [ "protected", "public" ] }, "share_url": { "description": "Owner-only persistent bearer link in protected mode; null when public or revoked.", "oneOf": [ { "type": "string", "format": "uri", "pattern": "^https://dev-[a-z0-9]+(?:-[a-z0-9]+){0,4}\\.(?:dev\\.)?check\\.omh\\.st/\\.ohmyhost/dev-access/redeem\\?stage=dev&ticket=[A-Za-z0-9_-]{43}$" }, { "type": "null" } ] } } }, "DevAccessTicket": { "type": "object", "additionalProperties": false, "required": [ "ticket_id", "project_id", "environment_id", "origin", "redeem_url", "expires_at" ], "properties": { "ticket_id": { "$ref": "#/components/schemas/Ulid" }, "project_id": { "$ref": "#/components/schemas/Ulid" }, "environment_id": { "$ref": "#/components/schemas/Ulid" }, "origin": { "type": "string", "format": "uri", "pattern": "^https://dev-[a-z0-9]+(?:-[a-z0-9]+){0,4}\\.(?:dev\\.)?check\\.omh\\.st$" }, "redeem_url": { "type": "string", "format": "uri", "pattern": "^https://dev-[a-z0-9]+(?:-[a-z0-9]+){0,4}\\.(?:dev\\.)?check\\.omh\\.st/\\.ohmyhost/dev-access/redeem\\?stage=dev&ticket=[A-Za-z0-9_-]{43}$" }, "expires_at": { "type": "string", "format": "date-time" } } }, "PlanDeploymentRequest": { "type": "object", "additionalProperties": false, "required": [ "commit_sha" ], "properties": { "commit_sha": { "$ref": "#/components/schemas/GitCommitSha" }, "environment": { "type": "string", "enum": [ "dev", "prod" ], "default": "dev", "description": "The environment the deployment builds into. Prod skips Dev and switches Prod traffic once activated." } } }, "CreateDeploymentRequest": { "type": "object", "additionalProperties": false, "required": [ "plan_id" ], "properties": { "plan_id": { "$ref": "#/components/schemas/Ulid" } } }, "DeploymentPlan": { "type": "object", "description": "Immutable pre-build deployment plan. It expires exactly 24 hours after creation.", "additionalProperties": false, "x-ohmyhost-ttl-seconds": 86400, "required": [ "id", "project_id", "environment", "commit_sha", "source_digest", "build_plan_digest", "application_root", "runtime", "route", "resource_effects", "limits", "estimated_cost", "risks", "destructive_effects", "required_confirmations", "created_at", "expires_at" ], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "project_id": { "$ref": "#/components/schemas/Ulid" }, "environment": { "type": "string", "enum": [ "dev", "prod" ], "description": "The environment this plan builds into." }, "commit_sha": { "$ref": "#/components/schemas/GitCommitSha" }, "source_digest": { "$ref": "#/components/schemas/Sha256Digest" }, "build_plan_digest": { "$ref": "#/components/schemas/Sha256Digest" }, "application_root": { "type": "string", "description": "Canonical repository-relative application root selected from immutable source evidence.", "readOnly": true, "maxLength": 64, "pattern": "^(?:\\.|[A-Za-z0-9][A-Za-z0-9._-]{0,62}(?:/[A-Za-z0-9][A-Za-z0-9._-]{0,62}){0,7})$" }, "artifact_digest": { "$ref": "#/components/schemas/Sha256Digest" }, "runtime": { "type": "string", "enum": [ "cloudflare_workers_static_assets", "cloudflare_workers_edge_ssr" ] }, "route": { "type": "string", "description": "Server-derived project-isolated public deployment URL; clients cannot select its gateway host or target Worker.", "format": "uri", "pattern": "^https://" }, "resource_effects": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 512 } }, "limits": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 512 } }, "estimated_cost": { "$ref": "#/components/schemas/CostEstimate" }, "risks": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 512 } }, "destructive_effects": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required_confirmations": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "CostEstimate": { "type": "object", "description": "Build-compute reservation quote, not the lifetime cost of the application. credits is the reserved amount in credits as a decimal (credit_micros divided by one million), the figure to show people. amount_micros is the customer USD equivalent of credit_micros; provider_cost_micros is the corresponding published provider-list basis. The versioned price is fixed by this immutable deployment plan. reserved_seconds is the reserved build time in seconds. The measured build seconds settle the reservation and unused credits are released. Storage, mail and runtime costs are separate.", "additionalProperties": false, "required": [ "amount_micros", "currency", "rate_card_version", "credit_micros", "credits", "provider_cost_micros", "scope", "reserved_seconds" ], "properties": { "amount_micros": { "type": "string", "pattern": "^[0-9]+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "rate_card_version": { "type": "string", "minLength": 1, "maxLength": 128 }, "credit_micros": { "type": "string", "pattern": "^[0-9]+$" }, "credits": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]{1,6})?$" }, "provider_cost_micros": { "type": "string", "pattern": "^[0-9]+$" }, "scope": { "type": "string", "const": "build_compute" }, "reserved_seconds": { "type": "string", "pattern": "^[1-9][0-9]*$" } } }, "Deployment": { "type": "object", "additionalProperties": false, "required": [ "id", "project_id", "operation_id", "commit_sha", "source_digest", "build_plan_digest", "status", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "project_id": { "$ref": "#/components/schemas/Ulid" }, "operation_id": { "$ref": "#/components/schemas/Ulid" }, "commit_sha": { "$ref": "#/components/schemas/GitCommitSha" }, "source_digest": { "$ref": "#/components/schemas/Sha256Digest" }, "build_plan_digest": { "$ref": "#/components/schemas/Sha256Digest" }, "artifact_digest": { "$ref": "#/components/schemas/Sha256Digest" }, "status": { "type": "string", "enum": [ "queued", "building", "publishing", "active", "failed", "rolled_back", "deleting", "deleted", "reconciliation_required" ] }, "url": { "type": "string", "description": "Project-isolated public gateway URL for the observed deployment.", "format": "uri", "pattern": "^https://" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DeploymentPage": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Deployment" } }, "next_cursor": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_-]+$" } } }, "GuardedActionPlan": { "type": "object", "description": "Non-mutating guarded-action plan with a confirmation token that expires exactly ten minutes after creation.", "additionalProperties": false, "x-ohmyhost-ttl-seconds": 600, "required": [ "action", "project_id", "resource_etag", "effects", "risks", "confirmation_token", "created_at", "expires_at" ], "properties": { "action": { "type": "string", "enum": [ "rollback", "promote", "delete" ] }, "project_id": { "$ref": "#/components/schemas/Ulid" }, "target_deployment_id": { "$ref": "#/components/schemas/Ulid" }, "target_artifact_digest": { "$ref": "#/components/schemas/Sha256Digest" }, "source_deployment_id": { "$ref": "#/components/schemas/Ulid" }, "source_artifact_digest": { "$ref": "#/components/schemas/Sha256Digest" }, "source_environment": { "type": "string", "const": "dev" }, "target_environment": { "type": "string", "const": "prod" }, "resource_etag": { "type": "string", "minLength": 3, "maxLength": 128, "description": "Send as If-Match with this plan's confirmation token." }, "effects": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 512 } }, "risks": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 512 } }, "confirmation_token": { "$ref": "#/components/schemas/ConfirmationToken" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "oneOf": [ { "properties": { "action": { "const": "rollback" } }, "required": [ "target_deployment_id", "target_artifact_digest" ] }, { "properties": { "action": { "const": "promote" } }, "required": [ "source_deployment_id", "source_artifact_digest", "source_environment", "target_environment" ] }, { "properties": { "action": { "const": "delete" } }, "not": { "anyOf": [ { "required": [ "target_deployment_id" ] }, { "required": [ "target_artifact_digest" ] }, { "required": [ "source_deployment_id" ] }, { "required": [ "source_artifact_digest" ] }, { "required": [ "source_environment" ] }, { "required": [ "target_environment" ] } ] } } ] }, "ConfirmationToken": { "type": "string", "description": "Opaque, single-action token bound to the planned action, project, target resource, and resource ETag.", "minLength": 32, "maxLength": 4096, "pattern": "^[A-Za-z0-9._~-]+$" }, "GitCommitSha": { "type": "string", "description": "Exact full Git commit object identifier; abbreviated or branch references are forbidden.", "pattern": "^[0-9a-f]{40}$" }, "Sha256Digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "ProjectDataMode": { "type": "string", "enum": [ "shared", "isolated" ], "default": "shared", "description": "Optional at creation, default shared. shared uses one data area across Dev/Prod; isolated gives each environment its own database/Auth records and file namespace. The four Owner-confirmed data-change actions reassign or reset areas without copying data or files and without a special change fee; ordinary measured resource consumption still applies. A reset or merge removes the named Dev resources. Promotion applies pending schema migrations to isolated Prod without copying Dev data." }, "HostingRegion": { "type": "string", "enum": [ "us", "eu" ], "default": "us", "description": "Chosen when the project is created and immutable afterwards. us (default) places the project's database, files, build sandbox and build objects in the US; eu places them in the EU. Prices are identical. ohmyhost.yaml storage.jurisdiction must equal this value." }, "FeedbackSubmission": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "kind", "title", "description" ], "dependentRequired": { "environment_id": [ "project_id" ], "operation_id": [ "project_id" ] }, "properties": { "organization_id": { "$ref": "#/components/schemas/Ulid" }, "project_id": { "$ref": "#/components/schemas/Ulid" }, "environment_id": { "$ref": "#/components/schemas/Ulid" }, "operation_id": { "$ref": "#/components/schemas/Ulid" }, "kind": { "type": "string", "enum": [ "bug", "issue", "feature_request" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Trimmed title without control characters." }, "description": { "type": "string", "minLength": 1, "maxLength": 8000, "description": "Trimmed, redacted expected/actual behavior and minimal reproduction. Line breaks and tabs are accepted; other control characters are rejected. Never include raw logs, environment files, credentials or personal records." }, "error_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,127}$", "maxLength": 128 }, "client_version": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,127}$", "maxLength": 128 } } }, "FeedbackReceipt": { "type": "object", "additionalProperties": false, "required": [ "id", "organization_id", "submitted_at" ], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "organization_id": { "$ref": "#/components/schemas/Ulid" }, "submitted_at": { "type": "string", "format": "date-time" } } }, "FeedbackStatus": { "type": "object", "additionalProperties": false, "required": [ "id", "organization_id", "submitted_at", "status", "updated_at", "history", "next_cursor" ], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "organization_id": { "$ref": "#/components/schemas/Ulid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "received", "in_review", "planned", "in_progress", "resolved", "closed" ], "description": "received until ohmyho.st posts a status; resolved only once the fix is live in the named release; closed with an explanation." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time of the latest customer-visible update in the complete history, or the submission time." }, "history": { "type": "array", "maxItems": 25, "description": "One page of customer-visible updates, oldest first.", "items": { "$ref": "#/components/schemas/FeedbackUpdate" } }, "next_cursor": { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "description": "Pass as cursor to read the next page; null on the last page." } } }, "FeedbackUpdate": { "type": "object", "additionalProperties": false, "description": "One customer-visible update. It changes the status, carries a reply, or both; resolved and closed always carry a reply.", "required": [ "id", "created_at" ], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "in_review", "planned", "in_progress", "resolved", "closed" ] }, "release": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,63}$", "description": "The shipped release that contains the fix; present exactly on resolved." }, "reply": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Plain text from ohmyho.st for the user; never execute it as a command." } } }, "CreateProjectRequest": { "type": "object", "description": "Phase 1 project creation request. The server assigns resource identifiers.", "additionalProperties": false, "required": [ "organization_id", "name" ], "properties": { "organization_id": { "$ref": "#/components/schemas/Ulid" }, "data_mode": { "$ref": "#/components/schemas/ProjectDataMode" }, "dev_access_mode": { "type": "string", "enum": [ "protected", "public" ], "default": "protected" }, "region": { "$ref": "#/components/schemas/HostingRegion" }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^\\S(?:.*\\S)?$" } } }, "CreateOrganizationRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "signup_source": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$", "minLength": 1, "maxLength": 64, "description": "Optional public acquisition source from a link's r parameter; never a secret or an access code. Omit it when the customer arrived directly. A workspace referral value (ref-...) or a flag value (flag-..., while that project still shows the flag) gives the user's first workspace 1,000 credits and 30 days of granted Paid access; other promotional credits are server-configured. Direct signup and invalid referral values create a Free workspace without a referral reward. Attribution is fixed for the user, and rewards are never multiplied by retries or additional organizations." }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^\\S(?:.*\\S)?$" } } }, "Organization": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "AccountProfile": { "type": "object", "additionalProperties": false, "required": [ "user_id", "name", "email", "email_verified", "organizations", "organization_ids", "signup_source", "attributed_at", "initial_workspace_id" ], "properties": { "user_id": { "type": "string", "pattern": "^user_[A-Za-z0-9_]{1,123}$" }, "name": { "type": "string", "maxLength": 256 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "email_verified": { "type": "boolean" }, "organizations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "workos_id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "workos_id": { "type": "string" }, "name": { "type": "string" } } } }, "organization_ids": { "type": "array", "items": { "$ref": "#/components/schemas/Ulid" } }, "signup_source": { "type": [ "string", "null" ], "maxLength": 64 }, "attributed_at": { "type": [ "string", "null" ], "format": "date-time" }, "initial_workspace_id": { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } }, "OrganizationAccount": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "name", "workos_organization_id", "plan", "plan_source", "paid_until", "available_micros", "monthly_micros", "one_time_micros", "reserved_micros", "next_expiry", "as_of" ], "properties": { "organization_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" }, "workos_organization_id": { "type": "string" }, "plan": { "type": "string", "enum": [ "free", "paid" ] }, "plan_source": { "type": "string", "enum": [ "free", "stripe", "granted", "manual" ] }, "paid_until": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the paid Stripe billing period or the applicable grant; null on Free or for an unbounded grant. During an unpaid renewal the effective Paid plan may remain available for up to 14 days after this Stripe period end, without new monthly credits." }, "available_micros": { "$ref": "#/components/schemas/CreditMicros" }, "monthly_micros": { "$ref": "#/components/schemas/CreditMicros" }, "one_time_micros": { "$ref": "#/components/schemas/CreditMicros" }, "reserved_micros": { "$ref": "#/components/schemas/CreditMicros" }, "next_expiry": { "type": [ "string", "null" ], "format": "date-time" }, "as_of": { "type": "string", "format": "date-time" } } }, "CurrentIdentity": { "type": "object", "description": "Minimal customer-visible identity and organization scope for authenticated agent clients.", "additionalProperties": false, "required": [ "actor_id", "organization_ids" ], "properties": { "actor_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "organization_ids": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/Ulid" } } } }, "Project": { "type": "object", "additionalProperties": false, "required": [ "id", "organization_id", "name", "handle", "data_mode", "region", "created_at" ], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "organization_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^\\S(?:.*\\S)?$" }, "handle": { "type": "string", "minLength": 3, "maxLength": 59, "pattern": "^[a-z0-9]+(-[a-z0-9]+){0,4}$" }, "data_mode": { "$ref": "#/components/schemas/ProjectDataMode" }, "region": { "$ref": "#/components/schemas/HostingRegion" }, "created_at": { "type": "string", "format": "date-time" } } }, "ProjectPage": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "next_cursor": { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } }, "ProjectEnvironment": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "ProjectHandleAvailability": { "type": "object", "additionalProperties": false, "required": [ "handle", "available", "alternatives" ], "properties": { "handle": { "type": "string", "description": "The handle exactly as it was asked about." }, "available": { "type": "boolean", "description": "True when a project may take this handle now." }, "reason": { "type": "string", "description": "Why the handle cannot be used. Absent when it is available.", "enum": [ "taken", "too_short", "too_long", "invalid_shape", "prohibited_word" ] }, "alternatives": { "type": "array", "description": "Free handles to offer instead, empty when the handle is available.", "maxItems": 5, "items": { "type": "string" } } } }, "ProjectStatus": { "type": "object", "additionalProperties": false, "required": [ "project_id", "etag", "handle", "region", "dev_access_mode", "lifecycle", "source", "default_environment", "head_deployment", "dev_url", "prod_url", "latest_operation", "cleanup_state" ], "properties": { "etag": { "type": "string", "pattern": "^\"sha256-[a-f0-9]{64}\"$", "description": "Optimistic-concurrency token for changing this project address; use it as If-Match on the handle endpoint." }, "project_id": { "$ref": "#/components/schemas/Ulid" }, "handle": { "type": "string", "minLength": 3, "maxLength": 59, "pattern": "^[a-z0-9]+(-[a-z0-9]+){0,4}$" }, "region": { "$ref": "#/components/schemas/HostingRegion" }, "dev_access_mode": { "type": "string", "enum": [ "protected", "public" ] }, "lifecycle": { "type": "string", "enum": [ "active", "deleting", "deleted" ] }, "source": { "oneOf": [ { "$ref": "#/components/schemas/ProjectSource" }, { "type": "null" } ] }, "default_environment": { "oneOf": [ { "$ref": "#/components/schemas/ProjectEnvironment" }, { "type": "null" } ] }, "environments": { "type": "array", "maxItems": 2, "description": "Tenant-scoped Dev and Prod environment IDs for secrets and other environment-scoped commands. Select by name; never infer the Prod ID from the default Dev environment.", "items": { "$ref": "#/components/schemas/ProjectEnvironment" } }, "head_deployment": { "oneOf": [ { "$ref": "#/components/schemas/Deployment" }, { "type": "null" } ] }, "dev_url": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^https://dev-[a-z0-9]+(?:-[a-z0-9]+){0,4}\\.(?:dev\\.)?check\\.omh\\.st$" }, { "type": "null" } ] }, "prod_url": { "oneOf": [ { "type": "string", "format": "uri", "pattern": "^https://[a-z0-9]+(?:-[a-z0-9]+){0,4}\\.(?:dev\\.)?check\\.omh\\.st$" }, { "type": "null" } ] }, "latest_operation": { "oneOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cleanup_state": { "type": "string", "enum": [ "not_started", "pending", "completed", "reconciliation_required" ] } } }, "ProblemDetails": { "type": "object", "description": "RFC 9457 Problem Details extended with stable ohmyhost recovery fields.", "additionalProperties": false, "required": [ "type", "title", "status", "code", "request_id", "retryable", "suggested_action" ], "properties": { "type": { "type": "string", "format": "uri-reference" }, "title": { "type": "string", "minLength": 1 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string" }, "instance": { "type": "string", "format": "uri-reference" }, "code": { "type": "string", "enum": [ "invalid_request", "unauthenticated", "forbidden", "organization_required", "resource_not_found", "idempotency_key_reused", "project_handle_unavailable", "project_identity_unavailable", "deployment_plan_expired", "deployment_plan_incompatible", "confirmation_expired", "confirmation_invalid", "etag_mismatch", "promotion_source_stale", "promotion_target_stale", "promotion_invalid_target", "mail_domain_conflict", "mail_domain_required", "mail_capacity_unavailable", "storage_jurisdiction_conflict", "shared_data_requires_promotion", "production_deployment_required", "framework_conversion_required", "repository_configuration_missing", "migration_filename_noncanonical", "environment_secret_mutation_blocked", "workers_runtime_incompatible", "project_handle_invalid", "project_handle_taken", "project_handle_unchanged", "project_rename_blocked", "payload_too_large", "rate_limited", "insufficient_organization_credits", "paid_plan_required", "project_budget_exceeded", "compute_performance_paid_required", "compute_performance_unavailable", "database_write_pending", "database_access_limit", "compute_change_pending", "compute_change_conflict", "billing_purchase_conflict", "billing_recharge_conflict", "github_connection_required", "github_connection_revoked", "repository_not_installed", "cloudflare_zone_not_bound", "cloudflare_authorization_closed", "project_notes_conflict", "project_export_not_ready", "powered_by_flag_required", "interactive_login_required", "api_key_creation_uncertain", "api_key_permissions_unavailable", "reconciliation_exhausted", "service_unavailable", "source_commit_not_found", "domain_hostname_taken", "domain_dns_conflict", "data_change_blocked", "data_change_in_progress", "data_change_not_applicable", "rollback_target_data_changed", "project_domain_delete_required" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "retryable": { "type": "boolean" }, "retry_after_seconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Optional machine-readable retry delay for a rate limit, matching Retry-After." }, "suggested_action": { "type": "string", "minLength": 1 } } }, "Operation": { "type": "object", "description": "Durable record returned for an accepted asynchronous mutation. Optional reconciliation is a current observation for queued/running work, separate from immutable terminal state. A completed reconciliation attempt alone does not mean the operation succeeded.", "additionalProperties": false, "required": [ "id", "state", "created_at", "updated_at" ], "properties": { "blocking_operation_id": { "description": "The active operation holding this queued operation's project mutation claim.", "$ref": "#/components/schemas/Ulid" }, "deployment_id": { "description": "The deployment this operation created (deploy, promotion or rollback), in every state. After a failure, read its diagnostics with deployment logs.", "$ref": "#/components/schemas/Ulid" }, "id": { "$ref": "#/components/schemas/Ulid" }, "state": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "result": { "type": "object", "additionalProperties": true }, "error": { "$ref": "#/components/schemas/OperationFailure" }, "progress": { "$ref": "#/components/schemas/OperationDeploymentProgress" }, "reconciliation": { "$ref": "#/components/schemas/OperationReconciliation" } } }, "OperationDeploymentProgress": { "type": "object", "additionalProperties": false, "description": "Current deployment dependency observation, separate from immutable operation history. Poll the same operation; mail readiness does not mean application activation.", "required": [ "phase", "project_id", "deployment_id", "observed_at", "next_poll_after_seconds", "suggested_action" ], "properties": { "build_completed_at": { "type": "string", "format": "date-time", "description": "Actual successful build completion time when this operation ran a build; omitted for reused artifacts without a current build." }, "phase": { "type": "string", "enum": [ "queued", "building", "publishing", "waiting_for_mail", "mail_status_unavailable" ] }, "project_id": { "$ref": "#/components/schemas/Ulid" }, "deployment_id": { "$ref": "#/components/schemas/Ulid" }, "observed_at": { "type": "string", "format": "date-time" }, "next_poll_after_seconds": { "type": "integer", "const": 60 }, "suggested_action": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "OperationReconciliation": { "type": "object", "additionalProperties": false, "required": [ "state", "attempt_id", "observed_at", "suggested_action" ], "properties": { "state": { "type": "string", "enum": [ "required", "pending" ] }, "attempt_id": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Active attempt for pending reconciliation; null when a new confirmed reconciliation is required." }, "observed_at": { "type": "string", "format": "date-time" }, "suggested_action": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "ProviderReconciliationAttempt": { "type": "object", "description": "Provider-neutral status of one idempotent reconciliation attempt.", "additionalProperties": false, "required": [ "reconciliation_id", "operation_id", "state" ], "properties": { "reconciliation_id": { "$ref": "#/components/schemas/Ulid" }, "operation_id": { "$ref": "#/components/schemas/Ulid" }, "state": { "type": "string", "enum": [ "completed", "pending", "uncertain" ] } } }, "IdempotencyConflictProblem": { "allOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "type": "object", "properties": { "code": { "const": "idempotency_key_reused" } } } ] }, "OperationEvent": { "type": "object", "additionalProperties": false, "required": [ "event_id", "operation_id", "project_id", "type", "occurred_at" ], "properties": { "event_id": { "$ref": "#/components/schemas/Ulid" }, "operation_id": { "$ref": "#/components/schemas/Ulid" }, "project_id": { "$ref": "#/components/schemas/Ulid" }, "type": { "type": "string", "enum": [ "OperationQueued", "OperationStarted", "OperationSucceeded", "OperationFailed", "OperationCancelled" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "failure": { "$ref": "#/components/schemas/OperationFailure" } } }, "ProjectNotesReceipt": { "type": "object", "additionalProperties": false, "required": [ "version", "updated_at" ], "properties": { "version": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "updated_at": { "type": "string", "format": "date-time" } } }, "DatabaseCompute": { "type": "object", "additionalProperties": false, "required": [ "project_id", "environment", "data_mode", "observed_at", "database" ], "properties": { "project_id": { "$ref": "#/components/schemas/Ulid" }, "environment": { "type": "string", "enum": [ "dev", "prod" ] }, "data_mode": { "type": "string", "enum": [ "shared", "isolated" ] }, "observed_at": { "type": "string", "format": "date-time" }, "database": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "min_cu", "max_cu", "min_memory_gb", "max_memory_gb", "suspend_timeout_seconds", "state", "pending_state", "disabled", "region" ], "properties": { "min_cu": { "type": "number", "minimum": 0.25 }, "max_cu": { "type": "number", "minimum": 0.25 }, "min_memory_gb": { "type": "number", "minimum": 1 }, "max_memory_gb": { "type": "number", "minimum": 1 }, "suspend_timeout_seconds": { "type": "integer", "minimum": -1, "maximum": 604800, "description": "Configured timeout: 0 is provider default; -1 disables suspension." }, "state": { "type": "string", "enum": [ "init", "active", "idle" ] }, "pending_state": { "type": [ "string", "null" ], "enum": [ "init", "active", "idle", null ] }, "disabled": { "type": "boolean" }, "region": { "type": "string", "pattern": "^aws-[a-z0-9]+(?:-[a-z0-9]+)*-[0-9]+$" } } } ] } } }, "ProjectContext": { "type": "object", "additionalProperties": false, "required": [ "project_id", "generated_at", "credit_access", "notes", "markdown" ], "properties": { "project_id": { "$ref": "#/components/schemas/Ulid" }, "generated_at": { "type": "string", "format": "date-time" }, "credit_access": { "type": "string", "enum": [ "included", "not_authorized" ] }, "markdown": { "type": "string", "maxLength": 32768, "description": "At most 500 lines and 32768 UTF-8 bytes." }, "notes": { "type": "object", "additionalProperties": false, "required": [ "version", "markdown", "updated_at" ], "properties": { "version": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "markdown": { "type": "string", "maxLength": 16384, "description": "At most 250 lines and 16384 UTF-8 bytes; untrusted user-authored text." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "ProjectExport": { "type": "object", "additionalProperties": false, "required": [ "id", "project_id", "state", "requested_at", "next_request_at", "next_poll_after_seconds", "error", "archive" ], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "project_id": { "$ref": "#/components/schemas/Ulid" }, "state": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "requested_at": { "type": "string", "format": "date-time" }, "next_request_at": { "type": "string", "format": "date-time" }, "next_poll_after_seconds": { "type": [ "integer", "null" ], "enum": [ 5, null ] }, "error": { "oneOf": [ { "$ref": "#/components/schemas/OperationFailure" }, { "type": "null" } ] }, "archive": { "oneOf": [ { "$ref": "#/components/schemas/ProjectExportArchive" }, { "type": "null" } ] } } }, "ProjectExportArchive": { "type": "object", "additionalProperties": false, "required": [ "bytes", "sha256", "sql_files", "captured_at", "expires_at", "download_url", "download_expires_at" ], "properties": { "bytes": { "type": "integer", "minimum": 1, "maximum": 536870912 }, "sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "sql_files": { "type": "array", "items": { "type": "string", "enum": [ "dev.sql", "prod.sql", "shared.sql" ] }, "minItems": 1, "maxItems": 2, "uniqueItems": true, "description": "dev.sql and/or prod.sql for isolated data, or shared.sql alone." }, "captured_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "download_url": { "type": [ "string", "null" ], "format": "uri" }, "download_expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "OperationFailure": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "retryable", "suggested_action" ], "properties": { "code": { "type": "string", "enum": [ "operation_failed", "operation_abandoned", "recovery_dispatch_failed", "recovery_job_failed", "recovery_input_expired", "recovery_database_unavailable", "recovery_checksum_mismatch", "recovery_scope_unavailable", "recovery_archive_too_large", "build_not_started", "build_failed", "database_write_rejected", "database_write_unavailable", "database_write_outcome_unknown", "database_compute_failed", "database_compute_plan_changed", "database_compute_rejected", "database_migration_failed", "insufficient_organization_credits", "paid_plan_required", "runtime_candidate_failed", "runtime_candidate_rejected", "storage_jurisdiction_conflict", "provider_state_absent", "auto_deploy_plan_rejected", "promotion_source_stale", "promotion_target_stale" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 512 }, "retryable": { "type": "boolean", "const": false, "description": "A terminal operation cannot be retried in place; follow suggested_action." }, "suggested_action": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "AuditEvent": { "type": "object", "additionalProperties": false, "required": [ "audit_event_id", "project_id", "event_type", "actor_type", "actor_id", "payload", "occurred_at" ], "properties": { "audit_event_id": { "$ref": "#/components/schemas/Ulid" }, "project_id": { "$ref": "#/components/schemas/Ulid" }, "operation_id": { "$ref": "#/components/schemas/Ulid" }, "event_type": { "type": "string", "minLength": 1 }, "actor_type": { "type": "string", "minLength": 1 }, "actor_id": { "type": "string", "minLength": 1 }, "payload": { "$ref": "#/components/schemas/AuditPayloadSummary" }, "occurred_at": { "type": "string", "format": "date-time" } } }, "AuditPayloadSummary": { "type": "object", "description": "A redacted, public summary of an internal audit payload.", "additionalProperties": false, "required": [ "summary" ], "properties": { "summary": { "type": "string", "minLength": 1, "maxLength": 512 } } }, "AuditEventPage": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "next_cursor": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_-]+$" } } }, "Ulid": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "ProjectDataChangeKind": { "type": "string", "enum": [ "isolate_prod_keeps_data", "isolate_dev_keeps_data", "share_prod_keeps_data", "reset_dev" ], "description": "Owner-confirmed assignment change. No application data is copied; physical resources are provisioned lazily." }, "ProjectDataChangeRequest": { "type": "object", "additionalProperties": false, "required": [ "change" ], "properties": { "change": { "$ref": "#/components/schemas/ProjectDataChangeKind" } } }, "ProjectDataChangePlan": { "type": "object", "additionalProperties": false, "required": [ "action", "project_id", "change", "data_mode_before", "data_mode_after", "effects", "destructive_effects", "redeploy_environments", "risks", "resource_etag", "confirmation_token", "created_at", "expires_at" ], "properties": { "action": { "type": "string", "const": "data_change" }, "project_id": { "$ref": "#/components/schemas/Ulid" }, "change": { "$ref": "#/components/schemas/ProjectDataChangeKind" }, "data_mode_before": { "type": "string", "enum": [ "shared", "isolated" ] }, "data_mode_after": { "type": "string", "enum": [ "shared", "isolated" ] }, "effects": { "type": "array", "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "destructive_effects": { "type": "array", "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "redeploy_environments": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "enum": [ "dev", "prod" ] } }, "risks": { "type": "array", "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "resource_etag": { "type": "string", "pattern": "^\"sha256-[a-f0-9]{64}\"$", "description": "Send as If-Match with this plan's confirmation token." }, "confirmation_token": { "$ref": "#/components/schemas/ConfirmationToken" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "description": "An action-bound ten-minute plan naming retained, retired and lazily created data areas. The workspace Owner confirms its destructive effects before execution." } } } }