@mortar-ai/skill 0.5.0 → 0.7.0

package/references/openapi.yaml

@@ -0,0 +1,2942 @@
+openapi: 3.0.3
+info:
+  title: Mortar REST API
+  version: "0.2.1"
+  description: |
+    Backend-as-a-Service for mainland-China-friendly mobile and web apps.
+
+    This file is authoritative for every operation, request, response, error,
+    security rule, and trust-surface extension it documents, but it is not yet
+    an exhaustive route inventory. `internal/api/routes.go` remains authoritative
+    for route existence. AI code generation must use documented operations and
+    must not invent a missing contract merely because a route exists in code.
+
+    Project-scope paths in this document use the internal and backward-
+    compatible `/v1/{tenant}/...` form so generic OpenAPI tooling can supply a
+    path parameter on the apex server.  The current SDK contract instead puts
+    the project UUID in the host and omits that path segment:
+    `https://<tenant>.api.mortar.appunvs.com/v1/...`.  Do not combine both forms.
+
+    Two authentication schemes coexist:
+      * `AccountToken` — Account session JWT minted by
+        `/v1/_accounts/signin`, or an Account PAT (`mtr_pat_*`); scopes all
+        `/v1/_accounts/*` and project-lifecycle calls to one Mortar account.
+      * `APIKey` — Bearer token starting with `mtr_live_` (production) or
+        `mtr_test_` (sandbox); scopes a single project (its tenant_id) and one of
+        `admin` / `app` / `public` privilege tiers.
+
+    Signed-in project users may additionally send a User access JWT in
+    `X-Mortar-User-Token`.  That optional identity layer is not modeled
+    consistently by every operation in this partial document.
+
+    Errors use a uniform `{ "error": "<machine_code>" }` body, occasionally
+    enriched with structured detail (see `tier_change_would_overflow`).
+  contact:
+    name: Mortar team
+    url: https://mortar.appunvs.com
+servers:
+  - url: https://api.mortar.appunvs.com
+    description: Production apex for account routes and path-form project examples in this reference
+  - url: http://localhost:8080
+    description: Local development apex
+
+x-mortar-ai-contract:
+  projectSourceOwner: fabric-harness-ai-turn
+  generatedSourceEndpoint: forbidden
+  defaultProjectCodeAccess: deny
+  description: |
+    Mortar publishes API contracts and live schema; it does not generate source
+    files for Fabric projects. Harness exposes only the operations relevant to a
+    turn, and the AI writes runtime-specific request, response, and application
+    types into ordinary project source. Operations marked projectCode: forbidden
+    are control-plane calls and must be reached only through their Harness tool.
+
+tags:
+  - name: accounts
+    description: Mortar-account signup / signin / profile + project lifecycle.
+  - name: projects
+    description: Account-scope CRUD over the projects an account owns.
+  - name: auth
+    description: Per-project User registration and sessions.
+  - name: data
+    description: Per-project key/value tables + rows.
+  - name: storage
+    description: Per-project blob storage with optional signed-URL downloads.
+  - name: realtime
+    description: Server-Sent-Events stream of row changes for a given table.
+  - name: usage
+    description: Project credit balance + compute-spec caps surfaced by `mortar usage me` and embedded usage widgets.
+  - name: compute
+    description: Per-project serverless functions (deploy / delete / invoke / logs).
+  - name: payment
+    description: Top-up flow + provider webhooks (WeChat Pay, Alipay).
+  - name: admin
+    description: Project-scope admin operations (currently API key minting).
+  - name: health
+    description: Liveness / readiness / status probes (no auth).
+  - name: cron
+    description: Per-project scheduled function invocations.
+  - name: queue
+    description: Durable background-job queue (Postgres-backed).
+  - name: comms
+    description: Messaging primitive — transactional email + SMS, billed per message per channel.
+  - name: tokens
+    description: Account-scope Personal Access Tokens (PATs, format `mtr_pat_*`) for CI / headless use.
+  - name: domains
+    description: Account-scoped hostname claim and DNS verification only; custom-host routing and TLS provisioning are not implemented.
+
+security:
+  - APIKey: []
+  - AccountToken: []
+
+paths:
+  /health:
+    get:
+      tags: [health]
+      summary: Combined liveness + readiness probe.
+      security: []
+      responses:
+        "200":
+          description: Service is up.
+        "503":
+          description: A required dependency (DB or Redis) is unreachable.
+
+  /health/live:
+    get:
+      tags: [health]
+      summary: Process-level liveness — returns 200 if the binary can serve.
+      security: []
+      responses:
+        "200":
+          description: Alive.
+
+  /health/ready:
+    get:
+      tags: [health]
+      summary: Readiness — fails when DB or Redis aren't reachable.
+      security: []
+      responses:
+        "200":
+          description: Ready to serve.
+        "503":
+          description: Not ready.
+
+  /status:
+    get:
+      tags: [health]
+      summary: Human-readable HTML status page.
+      security: []
+      responses:
+        "200":
+          description: HTML status page.
+
+  /v1/_accounts/signup:
+    post:
+      tags: [accounts]
+      summary: Create a new Mortar account.
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AccountSignupRequest"
+      responses:
+        "200":
+          description: Account created; JWT issued.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccountTokenResponse"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "409":
+          description: email_taken.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /v1/_accounts/signin:
+    post:
+      tags: [accounts]
+      summary: Sign in to an existing Mortar account.
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AccountSigninRequest"
+            examples:
+              standard:
+                value:
+                  email: dev@example.com
+                  password: hunter2hunter2
+      responses:
+        "200":
+          description: Signed in.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccountTokenResponse"
+              examples:
+                ok:
+                  value:
+                    token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+                    expires_at: "2026-05-20T10:30:00Z"
+                    account:
+                      id: acct_01HZ4
+                      email: dev@example.com
+                      name: Dev User
+                      created_at: "2026-04-12T09:11:00Z"
+        "401":
+          description: invalid_credentials.
+        "403":
+          description: suspended.
+
+  /v1/_accounts/me:
+    get:
+      tags: [accounts]
+      summary: Return the current account's profile.
+      security:
+        - AccountToken: []
+      responses:
+        "200":
+          description: Profile.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Account"
+        "401":
+          description: unauthorized.
+        "404":
+          description: not_found (account row missing).
+
+  /v1/_accounts/enterprise/contract:
+    get:
+      tags: [accounts]
+      summary: Return the authenticated Enterprise customer's logical capacity contract.
+      description: Physical cells, nodes, utilization, provider evidence, raw Mortar COGS, and publication operations are intentionally excluded.
+      security:
+        - AccountToken: []
+      responses:
+        "200":
+          description: Logical profiles, customer contract rates, and current admission availability.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EnterpriseContract"
+        "403":
+          description: enterprise_subscription_required.
+
+  /v1/_accounts/notification-email/start:
+    post:
+      tags: [accounts]
+      summary: Send a verification code to an operational notification email.
+      description: The verified address receives account credential-expiry reminders; it does not replace the login email.
+      security:
+        - AccountToken: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [email]
+              properties:
+                email:
+                  type: string
+                  format: email
+      responses:
+        "200":
+          description: Verification message accepted by the configured email provider.
+        "400":
+          description: invalid_body / invalid_email.
+        "429":
+          description: Verification send rate limit exceeded.
+        "502":
+          description: notification_email_delivery_failed.
+        "503":
+          description: notification_email_not_configured.
+
+  /v1/_accounts/notification-email/verify:
+    post:
+      tags: [accounts]
+      summary: Verify and bind the account's operational notification email.
+      security:
+        - AccountToken: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [email, code]
+              properties:
+                email:
+                  type: string
+                  format: email
+                code:
+                  type: string
+                  pattern: "^[0-9]{6}$"
+      responses:
+        "200":
+          description: Address verified and bound.
+        "400":
+          description: invalid_verification_code / verification_code_expired.
+        "429":
+          description: verification_attempts_exhausted.
+        "503":
+          description: notification_email_not_configured.
+
+  /v1/_accounts/projects:
+    post:
+      tags: [projects]
+      summary: Create a new project.
+      security:
+        - AccountToken: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ProjectCreateRequest"
+            examples:
+              subscription_default:
+                value:
+                  name: My App
+                  credit_mode: hard_budget
+      responses:
+        "201":
+          description: Created.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Project"
+              examples:
+                created:
+                  value:
+                    id: proj_01HZ4ABC
+                    name: My App
+                    compute_spec: nano
+                    tier: nano
+                    credit_mode: hard_budget
+                    created_at: "2026-05-13T10:00:00Z"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          description: unauthorized.
+        "403":
+          description: compute_spec_not_available or active_project_limit_reached for the account subscription.
+    get:
+      tags: [projects]
+      summary: List the account's projects, newest first.
+      security:
+        - AccountToken: []
+      responses:
+        "200":
+          description: Project list.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  projects:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/Project"
+        "401":
+          description: unauthorized.
+
+  /v1/_accounts/projects/{id}:
+    parameters:
+      - $ref: "#/components/parameters/ProjectIDPath"
+    get:
+      tags: [projects]
+      summary: Fetch a single project by id.
+      security:
+        - AccountToken: []
+      responses:
+        "200":
+          description: Project.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Project"
+        "404":
+          description: not_found (also returned for cross-account reads).
+    patch:
+      tags: [projects]
+      summary: Partial update (name, compute_spec, credit_mode, or Enterprise capacity_profile).
+      security:
+        - AccountToken: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ProjectUpdateRequest"
+      responses:
+        "200":
+          description: Updated.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Project"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "404":
+          description: not_found.
+        "409":
+          description: tier_change_would_overflow — see structured blockers.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TierOverflow"
+    delete:
+      tags: [projects]
+      summary: Soft-delete a project (30-day retention).
+      security:
+        - AccountToken: []
+      responses:
+        "204":
+          description: Deleted.
+        "404":
+          description: not_found.
+
+  /v1/_accounts/projects/{id}/write-suspension:
+    parameters:
+      - $ref: "#/components/parameters/ProjectIDPath"
+    put:
+      tags: [projects]
+      summary: Suspend or resume tenant mutations for an owned Enterprise capacity-profile project.
+      security:
+        - AccountToken: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ProjectWriteSuspensionRequest"
+      responses:
+        "200":
+          description: Write state updated or already converged.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProjectWriteSuspension"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          description: enterprise_capacity_project_required.
+        "404":
+          description: not_found.
+
+  /v1/_accounts/projects/{id}/topup:
+    parameters:
+      - $ref: "#/components/parameters/ProjectIDPath"
+    post:
+      tags: [payment]
+      summary: Initiate a manual top-up via WeChat Pay or Alipay.
+      security:
+        - AccountToken: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/TopupRequest"
+            examples:
+              wechat_50:
+                value:
+                  provider: wechat_pay
+                  amount_yuan: 50.0
+      responses:
+        "200":
+          description: Charge created — render QR or redirect the browser.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ChargeResult"
+              examples:
+                wechat:
+                  value:
+                    provider: wechat_pay
+                    external_ref: a1b2c3d4e5f6
+                    qr_code_data: weixin://wxpay/bizpayurl?pr=AbCdEfG
+                    expires_at_unix_sec: 1747130000
+        "400":
+          description: invalid_body / invalid_provider / amount_out_of_range.
+        "404":
+          description: not_found.
+        "502":
+          description: provider_call_failed.
+        "503":
+          description: provider_unavailable (no provider configured).
+
+  /v1/_webhooks/payment/{provider}:
+    parameters:
+      - name: provider
+        in: path
+        required: true
+        schema:
+          type: string
+          enum: [wechat_pay, alipay]
+    post:
+      tags: [payment]
+      summary: Provider webhook — signature-verified inline, no other auth.
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/WebhookEvent"
+      responses:
+        "200":
+          description: Event accepted (idempotent; duplicates are no-ops).
+        "400":
+          description: verify_failed / no_project_id / read_body.
+        "404":
+          description: unknown_provider.
+
+  /v1/{tenant}/_admin/keys:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [admin]
+      summary: Mint a new API key for the project (admin scope required).
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/APIKeyCreateRequest"
+      responses:
+        "201":
+          description: Key created — `raw_key` returned exactly once.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/APIKey"
+        "400":
+          description: invalid_body / name_required / invalid_scope.
+        "403":
+          description: admin_scope_required.
+
+  /v1/{tenant}/auth/signup:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [auth]
+      summary: Create a User inside this project.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UserAuthRequest"
+      responses:
+        "201":
+          description: User created.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UserAuthResponse"
+        "400":
+          description: invalid_body / email_invalid / password_too_short.
+        "409":
+          description: email_taken.
+
+  /v1/{tenant}/auth/signin:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [auth]
+      summary: Sign in as a User.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UserAuthRequest"
+      responses:
+        "200":
+          description: Signed in.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UserAuthResponse"
+        "401":
+          description: invalid_credentials.
+
+  /v1/{tenant}/auth/phone/start:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [auth]
+      summary: Start phone-OTP login — cache a 6-digit code + send via comms.sms.
+      description: |
+        Composes the `comms` (sms) + `cache` primitives. Send-side throttle
+        is enforced (60s cooldown per recipient, 10/day per recipient,
+        200/day per tenant — see auth.md). Returns 200 even if the phone
+        is new — phone-OTP find-or-creates the User on verify.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [phone]
+              properties:
+                phone:
+                  type: string
+                  description: E.164 phone (e.g. `+8613800138000`).
+      responses:
+        "200":
+          description: Code cached + SMS handed to the comms backend.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  sent:
+                    type: boolean
+                  expires_in_sec:
+                    type: integer
+        "400":
+          description: phone_invalid / invalid_body.
+        "429":
+          description: cooldown / daily_cap_recipient / daily_cap_tenant.
+        "503":
+          description: comms_not_configured.
+
+  /v1/{tenant}/auth/phone/verify:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [auth]
+      summary: Verify the SMS code — find-or-create a User by phone, mint JWT.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [phone, code]
+              properties:
+                phone:
+                  type: string
+                code:
+                  type: string
+      responses:
+        "200":
+          description: Code matched. User found-or-created, JWT issued.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UserAuthResponse"
+        "401":
+          description: invalid_code (wrong or expired).
+        "429":
+          description: too_many_attempts (verify attempt cap hit — code invalidated).
+
+  /v1/{tenant}/auth/email/verify/start:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [auth]
+      summary: Email a verification token to an existing User.
+      description: |
+        Always returns 200 — never reveals whether the email is registered.
+        Token TTL 15 min. Send-side throttle as above.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [email]
+              properties:
+                email:
+                  type: string
+      responses:
+        "200":
+          description: Sent (or silently no-op if no user).
+        "429":
+          description: cooldown / daily caps.
+
+  /v1/{tenant}/auth/email/verify/confirm:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [auth]
+      summary: Confirm the token, set `email_verified=true` on the User.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [email, token]
+              properties:
+                email:
+                  type: string
+                token:
+                  type: string
+      responses:
+        "200":
+          description: Marked verified (idempotent).
+        "401":
+          description: invalid_token.
+        "429":
+          description: too_many_attempts.
+
+  /v1/{tenant}/auth/password/reset/start:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [auth]
+      summary: Email a password-reset token to an existing User.
+      description: |
+        Always returns 200 (no enumeration). Token TTL 30 min.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [email]
+              properties:
+                email:
+                  type: string
+      responses:
+        "200":
+          description: Sent (or silently no-op if no user).
+        "429":
+          description: cooldown / daily caps.
+
+  /v1/{tenant}/auth/password/reset/confirm:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [auth]
+      summary: Consume the reset token, update the User's password hash.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [email, token, new_password]
+              properties:
+                email:
+                  type: string
+                token:
+                  type: string
+                new_password:
+                  type: string
+                  description: New password (>=8 chars).
+      responses:
+        "200":
+          description: Password updated.
+        "400":
+          description: password_too_short / email_or_token_invalid.
+        "401":
+          description: invalid_token.
+
+  /v1/{tenant}/comms/send:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [comms]
+      summary: Send one transactional message (email or sms) via the comms primitive.
+      description: |
+        Billed per message on the channel's resource (`email` or `sms`) in
+        the credit ledger. Aliyun SMS backends require a pre-registered
+        `template` code (模板报备).
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [channel, to]
+              properties:
+                channel:
+                  type: string
+                  enum: [email, sms]
+                to:
+                  type: string
+                  description: Email address (channel=email) or E.164 phone (channel=sms).
+                subject:
+                  type: string
+                  description: Email only.
+                body:
+                  type: string
+                template:
+                  type: string
+                  description: Provider template code (REQUIRED by real SMS providers).
+                vars:
+                  type: object
+                  additionalProperties:
+                    type: string
+      responses:
+        "201":
+          description: Accepted by the backend.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  channel:
+                    type: string
+                  to:
+                    type: string
+                  provider:
+                    type: string
+                    enum: [local, aliyun, tencent]
+        "400":
+          description: invalid_body / invalid_message.
+        "503":
+          description: comms_not_configured.
+
+  /v1/{tenant}/db/tables:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [data]
+      operationId: createDatabaseTableLegacy
+      x-mortar-trust-surface: harness-control
+      x-mortar-project-code: forbidden
+      summary: Create a table.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/TableCreateRequest"
+      responses:
+        "201":
+          description: Table created.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Table"
+        "400":
+          description: invalid_body / name_required / column_name_required.
+        "409":
+          description: table_exists.
+    get:
+      tags: [data]
+      operationId: listDatabaseTables
+      x-mortar-trust-surface: app-runtime
+      x-mortar-project-code: allowed
+      summary: List tables in this project.
+      security:
+        - APIKey: []
+      responses:
+        "200":
+          description: Tables.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tables:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/Table"
+
+  /v1/{tenant}/db/migrations/plan:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [data]
+      operationId: planDatabaseMigration
+      x-mortar-trust-surface: harness-control
+      x-mortar-project-code: forbidden
+      summary: Parse exact versioned SQL into a typed execution plan without mutation.
+      description: |
+        Harness-only control operation behind `mortar_migrate`. Application code
+        must not call this endpoint or embed an app/admin credential for it.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MigrationPlanRequest"
+      responses:
+        "200":
+          description: Language-neutral plan, diagnostics, exact checksum, and current tenant schema revision.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MigrationPlan"
+        "409":
+          description: The migration id is already recorded with different exact SQL bytes.
+
+  /v1/{tenant}/db/migrations/apply:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [data]
+      operationId: applyDatabaseMigration
+      x-mortar-trust-surface: harness-control
+      x-mortar-project-code: forbidden
+      summary: Atomically apply a reviewed exact-SQL migration and record its revision.
+      description: |
+        Re-parses the exact SQL, verifies SHA-256 and expected_revision, locks
+        this tenant's schema revision, then commits every logical schema
+        operation and the ledger row in one PostgreSQL transaction. Retrying an
+        already-recorded migration_id + checksum is idempotent.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MigrationApplyRequest"
+      responses:
+        "200":
+          description: Applied or idempotently confirmed.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MigrationApplyResponse"
+        "409":
+          description: Checksum or expected schema revision conflict.
+        "422":
+          description: The typed plan is not executable.
+
+  /v1/{tenant}/db/tables/{table}:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+      - $ref: "#/components/parameters/TablePath"
+    delete:
+      tags: [data]
+      operationId: dropDatabaseTableLegacy
+      x-mortar-trust-surface: harness-control
+      x-mortar-project-code: forbidden
+      summary: Drop the table.
+      security:
+        - APIKey: []
+      responses:
+        "204":
+          description: Dropped.
+
+  /v1/{tenant}/db/transactions:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [data]
+      operationId: executeDatabaseTransaction
+      x-mortar-trust-surface: trusted-server
+      x-mortar-project-code: trusted-server-only
+      summary: Atomically execute row writes and durable queue enqueues.
+      description: |
+        Runs every operation in one tenant-scoped PostgreSQL transaction. A
+        failure rolls back all preceding operations, including jobs inserted
+        into the PostgreSQL-backed queue. Requires an `app` or `admin` key;
+        object storage and other external providers are not part of this ACID
+        boundary. Maximum 200 operations and 1 MiB request body.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DBTransactionRequest"
+      responses:
+        "200":
+          description: Every operation committed.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DBTransactionResponse"
+        "400":
+          description: Invalid operation or missing required fields; nothing committed.
+        "404":
+          description: An update target was not found; nothing committed.
+        "503":
+          description: transactional_queue_not_configured when an enqueue was requested.
+
+  /v1/{tenant}/db/tables/{table}/rows:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+      - $ref: "#/components/parameters/TablePath"
+    post:
+      tags: [data]
+      operationId: insertDatabaseRows
+      x-mortar-trust-surface: app-runtime
+      x-mortar-project-code: allowed
+      summary: Atomically insert or upsert one or more rows.
+      description: |
+        A batch is atomic, but this POST is not retry-safe by itself. The API
+        provides no idempotency key or durable uniqueness constraint, and the
+        SDK does not automatically retry it. Client-side in-flight guards only
+        suppress duplicate interaction in that mounted client.
+      security:
+        - APIKey: []
+      parameters:
+        - name: upsert
+          in: query
+          description: When true, rows carrying an `id` replace that row; rows without an `id` insert.
+          schema:
+            type: boolean
+            default: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              oneOf:
+                - $ref: "#/components/schemas/RowBody"
+                - $ref: "#/components/schemas/RowBatchBody"
+      responses:
+        "201":
+          description: Inserted/upserted. Batch requests are all-or-nothing.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: "#/components/schemas/Row"
+                  - $ref: "#/components/schemas/RowsResponse"
+        "400":
+          description: invalid_body / table_required / missing_required_fields.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RowValidationError"
+    get:
+      tags: [data]
+      operationId: listDatabaseRows
+      x-mortar-trust-surface: app-runtime
+      x-mortar-project-code: allowed
+      summary: List rows; `?limit=N` (1..200, default 100).
+      security:
+        - APIKey: []
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 200
+      responses:
+        "200":
+          description: Rows.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RowsResponse"
+    patch:
+      tags: [data]
+      operationId: updateDatabaseRows
+      x-mortar-trust-surface: app-runtime
+      x-mortar-project-code: allowed
+      summary: Atomically partial-update rows selected by query filters.
+      description: |
+        Accepts the same PostgREST-style filters, ordering, limit, and offset as
+        GET. Matching rows are locked, partial-merged, validated, and updated in
+        one PostgreSQL transaction (maximum 200 affected rows). Full-text
+        search (`fts`) is rejected on mutation requests.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RowBody"
+      responses:
+        "200":
+          description: Updated rows.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RowsResponse"
+        "400":
+          description: Invalid filter/body or missing required fields; nothing updated.
+    delete:
+      tags: [data]
+      operationId: deleteDatabaseRows
+      x-mortar-trust-surface: app-runtime
+      x-mortar-project-code: allowed
+      summary: Atomically delete rows selected by query filters.
+      description: |
+        Accepts the same filters/order/limit/offset as GET. The returned rows
+        are exactly the rows deleted in the single transaction (maximum 200).
+        Full-text search (`fts`) is rejected on mutation requests.
+      security:
+        - APIKey: []
+      responses:
+        "200":
+          description: Deleted rows.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RowsResponse"
+
+  /v1/{tenant}/db/tables/{table}/rows/{id}:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+      - $ref: "#/components/parameters/TablePath"
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      tags: [data]
+      operationId: getDatabaseRow
+      x-mortar-trust-surface: app-runtime
+      x-mortar-project-code: allowed
+      summary: Fetch one row.
+      security:
+        - APIKey: []
+      responses:
+        "200":
+          description: Row.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Row"
+        "404":
+          description: not_found.
+    patch:
+      tags: [data]
+      operationId: updateDatabaseRow
+      x-mortar-trust-surface: app-runtime
+      x-mortar-project-code: allowed
+      summary: Patch a row's `data` blob.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RowBody"
+      responses:
+        "200":
+          description: Updated.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Row"
+        "400":
+          description: invalid_body / table_and_id_required / missing_required_fields.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RowValidationError"
+        "404":
+          description: not_found.
+    delete:
+      tags: [data]
+      operationId: deleteDatabaseRow
+      x-mortar-trust-surface: app-runtime
+      x-mortar-project-code: allowed
+      summary: Delete a row.
+      security:
+        - APIKey: []
+      responses:
+        "204":
+          description: Deleted.
+
+  /v1/{tenant}/storage/files:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [storage]
+      summary: Upload a single object — body is the raw bytes.
+      description: |
+        `?bucket=` and `?key=` are required. `Content-Type` carries the
+        MIME type (defaults to `application/octet-stream`). Max 50 MB per
+        request. Uploads use immutable physical versions: PostgreSQL atomically
+        switches the logical key only after the new bytes exist, while durable
+        cleanup records reclaim failed uploads and replaced versions.
+      security:
+        - APIKey: []
+      parameters:
+        - name: bucket
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: key
+          in: query
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
+      responses:
+        "201":
+          description: Uploaded.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FileObject"
+              examples:
+                avatar:
+                  value:
+                    bucket: avatars
+                    key: users/u_123/main.png
+                    size_bytes: 24817
+                    content_type: image/png
+                    created_at: "2026-05-13T10:42:00Z"
+        "400":
+          description: bucket_and_key_required.
+        "413":
+          description: file_too_large (> 50 MB).
+    get:
+      tags: [storage]
+      summary: List files (optionally filtered by `?bucket=`).
+      security:
+        - APIKey: []
+      parameters:
+        - name: bucket
+          in: query
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Files.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  files:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/FileObject"
+    delete:
+      tags: [storage]
+      summary: Delete the object.
+      description: Metadata deletion and a durable physical-cleanup record commit together; backend deletion is asynchronous and retried.
+      security:
+        - APIKey: []
+      parameters:
+        - name: bucket
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: key
+          in: query
+          required: true
+          description: Full object key, may contain slashes.
+          schema:
+            type: string
+      responses:
+        "204":
+          description: Deleted.
+
+  /v1/{tenant}/storage/sign/{bucket}/{key}:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+      - name: bucket
+        in: path
+        required: true
+        schema:
+          type: string
+      - name: key
+        in: path
+        required: true
+        schema:
+          type: string
+      - name: ttl_sec
+        in: query
+        description: TTL in seconds, clamped 60..86400; default 900.
+        schema:
+          type: integer
+          minimum: 60
+          maximum: 86400
+    get:
+      tags: [storage]
+      summary: Mint a short-lived signed URL pointing at the backend.
+      description: >-
+        Authorizes direct object-store access and does not consume the project's
+        API-concurrency budget. Signing is not proof of a download and does not
+        create an object-egress charge; actual object egress is accounted only
+        from provider-observed bytes.
+      security:
+        - APIKey: []
+      responses:
+        "200":
+          description: Signed URL.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SignedURL"
+        "404":
+          description: not_found.
+        "501":
+          description: backend_does_not_sign.
+
+  /v1/{tenant}/realtime/{table}:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+      - $ref: "#/components/parameters/TablePath"
+    get:
+      tags: [realtime]
+      summary: SSE stream of row changes (`insert` / `update` / `delete`).
+      security:
+        - APIKey: []
+      responses:
+        "200":
+          description: text/event-stream of change events.
+          content:
+            text/event-stream:
+              schema:
+                type: string
+        "500":
+          description: stream_not_supported (broker not wired).
+
+  /v1/{tenant}/usage/me:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    get:
+      tags: [usage]
+      summary: Project's credit balance + compute-spec caps (surfaced by `mortar usage me`).
+      security:
+        - APIKey: []
+      responses:
+        "200":
+          description: Usage summary.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UsageSummary"
+              examples:
+                nano_in_use:
+                  value:
+                    project_id: proj_01HZ4ABC
+                    billing_period: "2026-05"
+                    compute_spec: nano
+                    tier: nano
+                    credit_mode: hard_budget
+                    credit:
+                      granted_yuan: 99.0
+                      used_yuan: 12.34
+                      balance_yuan: 86.66
+                      used_by_resource:
+                        storage: 1.24
+                        network_egress: 7.00
+                        function: 4.10
+                    compute_spec_caps:
+                      capacity_units: 1
+                      compute_vcpu_slot: 0.05
+                      db_ram_gb: 1.0
+                      db_disk_gb: 10.0
+                      db_max_conns: 60
+                      cache_ram_mb: 64.0
+                      storage_gb: 10.0
+                      network_gb_per_month: 25.0
+                      function_cpu_min_per_month: 200
+                      log_ingest_gb_per_month: 1
+                      baseline_yuan_per_hour: 0.010011
+                      monthly_fee_yuan: 0
+                      reference_monthly_list_price_yuan: 28
+                      pricing_policy_version: 2026-08-cell-100pct-markup-300-nearest8-v4
+        "404":
+          description: not_found.
+
+  /v1/{tenant}/compute/functions/{name}:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+      - $ref: "#/components/parameters/FunctionNamePath"
+    post:
+      tags: [compute]
+      summary: Deploy (or overwrite) a function.  Max source 256 KB.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/FunctionDeployRequest"
+      responses:
+        "201":
+          description: Deployed.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FunctionView"
+        "400":
+          description: name_required / invalid_body / source_required.
+        "413":
+          description: source_too_large.
+        "503":
+          description: compute_not_configured.
+    delete:
+      tags: [compute]
+      summary: Delete the function (idempotent).
+      security:
+        - APIKey: []
+      responses:
+        "204":
+          description: Deleted.
+
+  /v1/{tenant}/compute/functions/{name}/invoke:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+      - $ref: "#/components/parameters/FunctionNamePath"
+    post:
+      tags: [compute]
+      summary: Invoke the function (body is forwarded as the event).
+      security:
+        - APIKey: []
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
+      responses:
+        "200":
+          description: Function response (shape function-defined).
+        "503":
+          description: compute_not_configured.
+    get:
+      tags: [compute]
+      summary: Same as POST /invoke but for HTTP-GET-style triggers.
+      security:
+        - APIKey: []
+      responses:
+        "200":
+          description: Function response.
+
+  /v1/{tenant}/compute/functions/{name}/logs:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+      - $ref: "#/components/parameters/FunctionNamePath"
+    get:
+      tags: [compute]
+      summary: Tail recent log entries for the function.
+      parameters:
+        - name: since
+          in: query
+          schema: {type: integer, format: int64}
+          description: Inclusive lower time bound in Unix milliseconds; defaults to ten minutes before until.
+        - name: until
+          in: query
+          schema: {type: integer, format: int64}
+          description: Upper time bound in Unix milliseconds; defaults to now.
+        - name: limit
+          in: query
+          schema: {type: integer, minimum: 1, maximum: 1000, default: 100}
+        - name: request
+          in: query
+          schema: {type: string}
+          description: Provider invocation ID filter.
+      security:
+        - APIKey: []
+      responses:
+        "200":
+          description: Entries.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  entries:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/LogEntry"
+        "503":
+          description: Managed-log primitive is not configured.
+        "502":
+          description: log_query_failed.
+
+  /v1/{tenant}/cron/schedules:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [cron]
+      operationId: createCronSchedule
+      summary: Create (or upsert) a cron schedule for a function.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CronScheduleCreateRequest"
+      responses:
+        "201":
+          description: Schedule created or updated.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CronSchedule"
+        "400":
+          description: invalid_body / fields_required / invalid_cron.
+    get:
+      tags: [cron]
+      operationId: listCronSchedules
+      summary: List all schedules in the tenant.
+      security:
+        - APIKey: []
+      responses:
+        "200":
+          description: Schedules.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  schedules:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/CronSchedule"
+
+  /v1/{tenant}/cron/schedules/{name}:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+      - name: name
+        in: path
+        required: true
+        schema:
+          type: string
+    patch:
+      tags: [cron]
+      operationId: patchCronSchedule
+      summary: Toggle the enabled flag on a schedule.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CronSchedulePatchRequest"
+      responses:
+        "204":
+          description: Updated.
+        "400":
+          description: invalid_body / name_required / enabled_required.
+        "404":
+          description: not_found.
+    delete:
+      tags: [cron]
+      operationId: deleteCronSchedule
+      summary: Delete a schedule (idempotent).
+      security:
+        - APIKey: []
+      responses:
+        "204":
+          description: Deleted.
+        "400":
+          description: name_required.
+
+  /v1/{tenant}/queue/jobs:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+    post:
+      tags: [queue]
+      operationId: enqueueJob
+      summary: Enqueue a background job.
+      security:
+        - APIKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/QueueEnqueueRequest"
+      responses:
+        "201":
+          description: Created — server fills in id / status / timestamps.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Job"
+        "400":
+          description: invalid_body / type_required / invalid_run_at.
+        "503":
+          description: queue_not_configured.
+    get:
+      tags: [queue]
+      operationId: listJobs
+      summary: List jobs in the tenant (filterable).
+      security:
+        - APIKey: []
+      parameters:
+        - name: type
+          in: query
+          schema:
+            type: string
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [pending, running, completed, failed]
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 50
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            default: 0
+      responses:
+        "200":
+          description: Jobs page.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  jobs:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/Job"
+        "503":
+          description: queue_not_configured.
+
+  /v1/{tenant}/queue/jobs/{id}:
+    parameters:
+      - $ref: "#/components/parameters/TenantPath"
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      tags: [queue]
+      operationId: getJob
+      summary: Fetch one job by ID.
+      security:
+        - APIKey: []
+      responses:
+        "200":
+          description: Job.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Job"
+        "400":
+          description: id_required.
+        "404":
+          description: not_found.
+        "503":
+          description: queue_not_configured.
+
+  /v1/_accounts/tokens:
+    post:
+      tags: [tokens]
+      operationId: createAccountToken
+      summary: Mint a fixed-lived Personal Access Token (`mtr_pat_*`) for the current account.
+      description: |
+        Raw key is returned exactly ONCE in `raw_key`; subsequent reads only
+        expose the prefix and metadata. Use the raw value as
+        `Authorization: Bearer <raw_key>` against any account-scope endpoint
+        — or as `MORTAR_ACCOUNT_TOKEN` env var for the CLI in CI / headless
+        contexts. Every token has a fixed expiry. `expires_in_days` accepts
+        1-365; omit / 0 selects the one-year default.
+      security:
+        - AccountToken: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AccountTokenCreateRequest"
+      responses:
+        "201":
+          description: Token created. `raw_key` shown once.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccountTokenCreated"
+        "400":
+          description: invalid_body / name_required / invalid_token_expiry.
+    get:
+      tags: [tokens]
+      operationId: listAccountTokens
+      summary: List non-revoked PATs for the current account.
+      security:
+        - AccountToken: []
+      responses:
+        "200":
+          description: Tokens.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tokens:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/AccountTokenView"
+
+  /v1/_accounts/tokens/{id}:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+    delete:
+      tags: [tokens]
+      operationId: revokeAccountToken
+      summary: Revoke a PAT. Idempotent.
+      security:
+        - AccountToken: []
+      responses:
+        "204":
+          description: Revoked.
+        "404":
+          description: not_found (token doesn't exist or belongs to a different account).
+
+  /v1/_accounts/projects/{id}/domains:
+    parameters:
+      - $ref: "#/components/parameters/ProjectIDPath"
+    post:
+      tags: [domains]
+      operationId: createCustomDomain
+      summary: Claim a custom hostname; returns the TXT record to publish.
+      security:
+        - AccountToken: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CustomDomainCreateRequest"
+      responses:
+        "201":
+          description: Claim created; publish TXT then call /verify.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomDomain"
+        "400":
+          description: invalid_body / hostname_required / id_required.
+        "403":
+          description: forbidden.
+        "404":
+          description: not_found.
+        "409":
+          description: hostname_taken.
+    get:
+      tags: [domains]
+      operationId: listCustomDomains
+      summary: List custom domains attached to the project.
+      security:
+        - AccountToken: []
+      responses:
+        "200":
+          description: Domains.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  domains:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/CustomDomain"
+        "403":
+          description: forbidden.
+        "404":
+          description: not_found.
+
+  /v1/_accounts/projects/{id}/domains/{hostname}/verify:
+    parameters:
+      - $ref: "#/components/parameters/ProjectIDPath"
+      - name: hostname
+        in: path
+        required: true
+        schema:
+          type: string
+    post:
+      tags: [domains]
+      operationId: verifyCustomDomain
+      summary: Verify ownership via DNS TXT lookup; stamp verified_at.
+      security:
+        - AccountToken: []
+      responses:
+        "200":
+          description: Verified.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomDomain"
+        "400":
+          description: hostname_required.
+        "403":
+          description: forbidden.
+        "404":
+          description: not_found.
+        "412":
+          description: txt_not_found (publish TXT then retry).
+        "502":
+          description: dns_lookup_failed.
+
+  /v1/_accounts/projects/{id}/domains/{hostname}:
+    parameters:
+      - $ref: "#/components/parameters/ProjectIDPath"
+      - name: hostname
+        in: path
+        required: true
+        schema:
+          type: string
+    delete:
+      tags: [domains]
+      operationId: deleteCustomDomain
+      summary: Release a custom domain claim.
+      security:
+        - AccountToken: []
+      responses:
+        "204":
+          description: Deleted.
+        "400":
+          description: hostname_required.
+        "403":
+          description: forbidden.
+        "404":
+          description: not_found.
+
+components:
+  securitySchemes:
+    AccountToken:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT or mtr_pat_*
+      description: |
+        Account-scope auth for every `/v1/_accounts/*` route.  Two token
+        kinds are accepted in the same `Authorization: Bearer …` slot:
+        the JWT minted by `/v1/_accounts/signin` (default-TTL session) and
+        a fixed-lived Personal Access Token (`mtr_pat_*`) minted via
+        `POST /v1/_accounts/tokens`.  PATs are intended for CI / headless
+        use and may be passed via the `MORTAR_ACCOUNT_TOKEN` env var to
+        the `mortar` CLI.
+    APIKey:
+      type: http
+      scheme: bearer
+      bearerFormat: opaque
+      description: |
+        Project-scope API key starting with `mtr_live_` (production) or
+        `mtr_test_` (sandbox).  Bearer-encoded in `Authorization`.
+
+  parameters:
+    TenantPath:
+      name: tenant
+      in: path
+      required: true
+      description: |
+        Tenant ID — the data-isolation boundary.  Its value is the
+        project's UUID (the API-key's project; project = the tenant).
+      schema:
+        type: string
+    ProjectIDPath:
+      name: id
+      in: path
+      required: true
+      schema:
+        type: string
+    TablePath:
+      name: table
+      in: path
+      required: true
+      schema:
+        type: string
+    FunctionNamePath:
+      name: name
+      in: path
+      required: true
+      schema:
+        type: string
+
+  responses:
+    BadRequest:
+      description: Malformed request.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+
+  schemas:
+    Error:
+      type: object
+      required: [error]
+      properties:
+        error:
+          type: string
+          description: Machine-readable error code (e.g. `invalid_body`).
+        detail:
+          type: string
+
+    Account:
+      type: object
+      required: [id, email, subscription_plan, subscription_contract_only, allowed_compute_specs, max_active_projects, created_at]
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+        subscription_plan:
+          type: string
+          enum: [free, pro, team, enterprise]
+        subscription_valid_until:
+          type: string
+          format: date-time
+        subscription_monthly_fee_yuan:
+          type: number
+          format: double
+        subscription_compute_grant_yuan:
+          type: number
+          format: double
+        subscription_settlement_kind:
+          type: string
+          enum: [online_payment, aggregate_invoice, contract_invoice]
+        subscription_contract_only:
+          type: boolean
+          description: True for Enterprise; commercial terms are absent until an immutable contract period exists.
+        allowed_compute_specs:
+          type: array
+          items:
+            type: string
+            enum: [nano, micro, small, medium, large, xl, 2xl, 4xl, 8xl, 16xl]
+        max_active_projects:
+          type: integer
+          minimum: 0
+          description: Account-level active-project ceiling; 0 means no catalog-level count ceiling.
+        notification_email:
+          type: string
+          format: email
+          description: Present only after proof of control.
+        notification_email_verified_at:
+          type: string
+          format: date-time
+        created_at:
+          type: string
+          format: date-time
+
+    AccountSignupRequest:
+      type: object
+      required: [email, password]
+      properties:
+        email:
+          type: string
+          format: email
+        password:
+          type: string
+          minLength: 8
+        name:
+          type: string
+
+    AccountSigninRequest:
+      type: object
+      required: [email, password]
+      properties:
+        email:
+          type: string
+        password:
+          type: string
+
+    AccountTokenResponse:
+      type: object
+      required: [token, expires_at, account]
+      properties:
+        token:
+          type: string
+        expires_at:
+          type: string
+          format: date-time
+        account:
+          $ref: "#/components/schemas/Account"
+
+    Project:
+      type: object
+      description: "A project has exactly one customer resource-spec axis: compute_spec for retail compute, or capacity_profile for an Enterprise capacity contract."
+      required: [id, name, credit_mode, created_at]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        compute_spec:
+          type: string
+          enum: [nano, micro, small, medium, large, xl, 2xl, 4xl, 8xl, 16xl]
+          description: Retail compute specification; omitted when capacity_profile is present.
+        tier:
+          type: string
+          enum: [nano, micro, small, medium, large, xl, 2xl, 4xl, 8xl, 16xl]
+          deprecated: true
+          description: Compatibility alias for compute_spec; omitted on Enterprise capacity projects.
+        credit_mode:
+          type: string
+          enum: [hard_budget, post_pay]
+        capacity_profile:
+          type: string
+          description: Logical profile on an Enterprise capacity project; mutually exclusive with compute_spec and tier.
+        created_at:
+          type: string
+          format: date-time
+
+    ProjectCreateRequest:
+      type: object
+      required: [name]
+      properties:
+        name:
+          type: string
+        compute_spec:
+          type: string
+          enum: [nano, micro, small, medium, large, xl, 2xl, 4xl, 8xl, 16xl]
+        tier:
+          type: string
+          enum: [nano, micro, small, medium, large, xl, 2xl, 4xl, 8xl, 16xl]
+          deprecated: true
+        credit_mode:
+          type: string
+        capacity_profile:
+          type: string
+          description: Enterprise only; mutually exclusive with compute_spec and tier.
+
+    ProjectUpdateRequest:
+      type: object
+      properties:
+        name:
+          type: string
+        compute_spec:
+          type: string
+          enum: [nano, micro, small, medium, large, xl, 2xl, 4xl, 8xl, 16xl]
+        tier:
+          type: string
+          enum: [nano, micro, small, medium, large, xl, 2xl, 4xl, 8xl, 16xl]
+          deprecated: true
+        credit_mode:
+          type: string
+        capacity_profile:
+          type: string
+          description: Enterprise only; changes the owned project's logical profile through Mortar admission. Mutually exclusive with compute_spec and tier; a placed capacity project cannot be changed through the retail compute_spec axis.
+
+    EnterpriseContract:
+      type: object
+      required: [generated_at, profiles, profile_rates, usage_rates, admission_open]
+      properties:
+        generated_at:
+          type: string
+          format: date-time
+        profiles:
+          type: array
+          items:
+            $ref: "#/components/schemas/EnterpriseCapacityProfile"
+        profile_rate_version:
+          type: string
+        profile_rates:
+          type: array
+          items:
+            $ref: "#/components/schemas/EnterpriseProfileRate"
+        usage_rate_version:
+          type: string
+        usage_rates:
+          type: array
+          items:
+            $ref: "#/components/schemas/EnterpriseUsageRate"
+        admission_open:
+          type: boolean
+
+    EnterpriseCapacityProfile:
+      type: object
+      required: [id, display_name, admission_units, max_api_concurrency, max_db_query_concurrency, max_realtime_connections, max_function_concurrency, hot_tenant_eligibility, security_isolation]
+      properties:
+        id: {type: string}
+        display_name: {type: string}
+        admission_units: {type: integer, format: int64}
+        max_api_concurrency: {type: integer}
+        max_db_query_concurrency: {type: integer}
+        max_realtime_connections: {type: integer}
+        max_function_concurrency: {type: integer}
+        hot_tenant_eligibility: {type: string}
+        security_isolation: {type: string}
+
+    EnterpriseProfileRate:
+      type: object
+      required: [profile_id, rate_version, hourly_rate_micros]
+      properties:
+        profile_id: {type: string}
+        rate_version: {type: string}
+        hourly_rate_micros: {type: integer, format: int64}
+
+    EnterpriseUsageRate:
+      type: object
+      required: [resource, native_unit, billing_unit, native_units_per_billing_unit, rate_micros_per_billing_unit]
+      properties:
+        resource: {type: string}
+        native_unit: {type: string}
+        billing_unit: {type: string}
+        native_units_per_billing_unit: {type: number, format: double}
+        rate_micros_per_billing_unit: {type: integer, format: int64}
+
+    ProjectWriteSuspensionRequest:
+      type: object
+      required: [suspended]
+      properties:
+        suspended:
+          type: boolean
+        reason:
+          type: string
+          minLength: 3
+          maxLength: 200
+          description: Required when suspended is true; ignored when resuming.
+
+    ProjectWriteSuspension:
+      type: object
+      required: [project_id, write_suspended, reason]
+      properties:
+        project_id:
+          type: string
+        write_suspended:
+          type: boolean
+        reason:
+          type: string
+        suspended_at:
+          type: string
+          format: date-time
+
+    TierOverflow:
+      type: object
+      properties:
+        error:
+          type: string
+          example: tier_change_would_overflow
+        target:
+          type: string
+        blockers:
+          type: array
+          items:
+            type: object
+            properties:
+              resource:
+                type: string
+              current:
+                type: integer
+                format: int64
+              new_limit:
+                type: integer
+                format: int64
+
+    TopupRequest:
+      type: object
+      required: [provider, amount_yuan]
+      properties:
+        provider:
+          type: string
+          enum: [wechat_pay, alipay]
+        amount_yuan:
+          type: number
+          format: double
+          minimum: 1.0
+          maximum: 10000.0
+        method:
+          type: string
+          description: Optional alipay sub-method (`scan` / `page`).
+
+    ChargeResult:
+      type: object
+      required: [provider, external_ref]
+      properties:
+        provider:
+          type: string
+        external_ref:
+          type: string
+        qr_code_data:
+          type: string
+        redirect_url:
+          type: string
+        expires_at_unix_sec:
+          type: integer
+          format: int64
+
+    WebhookEvent:
+      type: object
+      description: |
+        Provider-shaped payload — the body is opaque to Mortar; the
+        provider's `VerifyWebhook` parses + normalises it.
+      additionalProperties: true
+
+    APIKeyCreateRequest:
+      type: object
+      required: [name]
+      properties:
+        name:
+          type: string
+        scope:
+          type: string
+          enum: [admin, app, public]
+          default: app
+        env:
+          type: string
+          enum: [live, test]
+          default: live
+
+    APIKey:
+      type: object
+      required: [id, name, prefix, scope, raw_key, created_at]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        prefix:
+          type: string
+          example: mtr_live_abcd
+        scope:
+          type: string
+          enum: [admin, app, public]
+        raw_key:
+          type: string
+          description: Full key, returned ONCE at creation time.
+        created_at:
+          type: string
+          format: date-time
+
+    UserAuthRequest:
+      type: object
+      required: [email, password]
+      properties:
+        email:
+          type: string
+          format: email
+        password:
+          type: string
+          minLength: 8
+
+    UserAuthResponse:
+      type: object
+      required: [access_token, user_id, expires_in_sec]
+      properties:
+        access_token:
+          type: string
+        refresh_token:
+          type: string
+        user_id:
+          type: string
+        email:
+          type: string
+        phone:
+          type: string
+        data_role:
+          type: string
+          enum: [user, admin]
+        expires_in_sec:
+          type: integer
+        refresh_expires_in_sec:
+          type: integer
+
+    TableColumn:
+      type: object
+      required: [name, type]
+      properties:
+        name:
+          type: string
+        type:
+          type: string
+          enum: [text, number, bool, json, timestamp, uuid]
+        required:
+          type: boolean
+
+    MigrationPlanRequest:
+      type: object
+      required: [migration_id, sql]
+      properties:
+        migration_id:
+          type: string
+          pattern: '^[0-9]{4,14}_[a-z0-9][a-z0-9_]*\.sql$'
+          example: 0007_create_orders.sql
+        sql:
+          type: string
+          description: Exact Mortar logical SQL bytes represented as a JSON string.
+
+    MigrationApplyRequest:
+      allOf:
+        - $ref: "#/components/schemas/MigrationPlanRequest"
+        - type: object
+          required: [checksum, expected_revision]
+          properties:
+            checksum:
+              type: string
+              pattern: '^sha256:[a-f0-9]{64}$'
+            expected_revision:
+              type: integer
+              format: int64
+              minimum: 0
+
+    MigrationOperation:
+      type: object
+      required: [kind, table]
+      properties:
+        kind:
+          type: string
+          enum: [create_table, drop_table, set_table_access, add_column, drop_column, create_index]
+        table:
+          type: string
+        access:
+          type: string
+          enum: [private, public_read, public, public_insert, app_only]
+        columns:
+          type: array
+          items:
+            $ref: "#/components/schemas/TableColumn"
+        column:
+          type: string
+        type:
+          type: string
+          enum: [text, number, bool, json, timestamp, uuid]
+        required:
+          type: boolean
+        fields:
+          type: array
+          items:
+            type: string
+
+    MigrationDiagnostic:
+      type: object
+      required: [severity, code, message]
+      properties:
+        severity:
+          type: string
+          enum: [warning, error]
+        code:
+          type: string
+        message:
+          type: string
+        statement:
+          type: integer
+
+    MigrationPlan:
+      type: object
+      required: [version, migration_id, checksum, current_revision, operations, diagnostics, destructive, executable]
+      properties:
+        version:
+          type: string
+          enum: [mortar.migration-plan.v1]
+        migration_id:
+          type: string
+        checksum:
+          type: string
+        current_revision:
+          type: integer
+          format: int64
+        operations:
+          type: array
+          items:
+            $ref: "#/components/schemas/MigrationOperation"
+        diagnostics:
+          type: array
+          items:
+            $ref: "#/components/schemas/MigrationDiagnostic"
+        destructive:
+          type: boolean
+        executable:
+          type: boolean
+        already_applied:
+          type: boolean
+
+    MigrationApplyResponse:
+      type: object
+      required: [plan, revision, applied]
+      properties:
+        plan:
+          $ref: "#/components/schemas/MigrationPlan"
+        revision:
+          type: integer
+          format: int64
+        applied:
+          type: boolean
+
+    TableCreateRequest:
+      type: object
+      required: [name]
+      properties:
+        name:
+          type: string
+        columns:
+          type: array
+          items:
+            type: object
+            required: [name]
+            properties:
+              name:
+                type: string
+              type:
+                type: string
+              required:
+                type: boolean
+
+    Table:
+      type: object
+      properties:
+        name:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+        columns:
+          type: array
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+              type:
+                type: string
+              required:
+                type: boolean
+
+    RowBody:
+      type: object
+      description: >
+        Row insert / update envelope.  The row's actual fields go under
+        the `data` key — sending a flat body (e.g. `{"email": "..."}`
+        directly) writes an empty row, because the server only reads
+        the `data` property.  `id`, `created_at`, and `updated_at` are
+        server-owned metadata rather than application payload fields.
+      required: [data]
+      properties:
+        data:
+          type: object
+          description: >
+            The row's JSONB payload.  Keys declared as `required: true`
+            on the table (see TableCreateRequest) must be present and
+            non-null, otherwise the server returns 400
+            missing_required_fields.  Logical type names inform AI-authored
+            application types but are not runtime value validators.  Do not
+            send the server-owned `id`, `created_at`, or `updated_at` keys in
+            ordinary insert/update payloads; documented upsert may use `id`
+            only as row identity.
+          additionalProperties: true
+
+    RowBatchBody:
+      type: object
+      required: [rows]
+      properties:
+        rows:
+          type: array
+          minItems: 1
+          maxItems: 200
+          items:
+            type: object
+            additionalProperties: true
+      description: >
+        All rows are inserted/upserted in one PostgreSQL transaction.  Batch
+        atomicity does not make retrying this POST idempotent.  Each item is an
+        application payload; omit server-owned `id`, `created_at`, and
+        `updated_at` except that upsert may use `id` through its documented SDK
+        contract.
+
+    Row:
+      type: object
+      description: >
+        Stored row envelope.  The SDK flattens the server-owned `id`,
+        `created_at`, and `updated_at` metadata beside the application payload
+        when it returns a row; those names are not application-owned fields.
+      properties:
+        id:
+          type: string
+        table:
+          type: string
+        data:
+          type: object
+          additionalProperties: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    RowsResponse:
+      type: object
+      required: [rows]
+      properties:
+        rows:
+          type: array
+          items:
+            $ref: "#/components/schemas/Row"
+
+    DBTransactionRequest:
+      type: object
+      required: [operations]
+      properties:
+        operations:
+          type: array
+          minItems: 1
+          maxItems: 200
+          items:
+            $ref: "#/components/schemas/DBTransactionOperation"
+
+    DBTransactionOperation:
+      type: object
+      required: [op]
+      description: |
+        `insert`: table + data. `update`: table + UUID id + complete replacement
+        data. `delete`: table + UUID id. `enqueue`: type plus optional payload,
+        run_at, and max_attempts.
+      properties:
+        op:
+          type: string
+          enum: [insert, update, delete, enqueue]
+        table:
+          type: string
+        id:
+          type: string
+          format: uuid
+        data:
+          type: object
+          additionalProperties: true
+        type:
+          type: string
+        payload: {}
+        run_at:
+          type: string
+          format: date-time
+        max_attempts:
+          type: integer
+
+    DBTransactionResponse:
+      type: object
+      required: [results]
+      properties:
+        results:
+          type: array
+          items:
+            type: object
+            required: [op]
+            properties:
+              op:
+                type: string
+              row:
+                $ref: "#/components/schemas/Row"
+              job:
+                $ref: "#/components/schemas/Job"
+
+    RowValidationError:
+      type: object
+      description: >
+        Returned on 400 when the row body fails validation.  `error` is
+        the machine-readable code; `fields` (only for
+        `missing_required_fields`) lists the column names that were
+        absent / null.
+      required: [error]
+      properties:
+        error:
+          type: string
+          enum:
+            - invalid_body
+            - table_required
+            - table_and_id_required
+            - missing_required_fields
+        fields:
+          type: array
+          items:
+            type: string
+
+    FileObject:
+      type: object
+      required: [bucket, key, size_bytes, content_type, created_at]
+      properties:
+        bucket:
+          type: string
+        key:
+          type: string
+        size_bytes:
+          type: integer
+          format: int64
+        content_type:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+
+    SignedURL:
+      type: object
+      properties:
+        url:
+          type: string
+        expires_in_sec:
+          type: integer
+          format: int64
+        size_bytes:
+          type: integer
+          format: int64
+          description: Object metadata only; it is not a billed egress projection.
+
+    UsageSummary:
+      type: object
+      properties:
+        project_id:
+          type: string
+        billing_period:
+          type: string
+          example: "2026-05"
+        compute_spec:
+          type: string
+        tier:
+          type: string
+          deprecated: true
+        credit_mode:
+          type: string
+        credit:
+          type: object
+          properties:
+            granted_yuan:
+              type: number
+            used_yuan:
+              type: number
+            balance_yuan:
+              type: number
+            used_by_resource:
+              type: object
+              additionalProperties:
+                type: number
+        compute_spec_caps:
+          type: object
+          properties:
+            capacity_units:
+              type: integer
+              format: int64
+            compute_vcpu_slot:
+              type: number
+              description: vCPU share allocated to this tenant from the pool ECS.
+            db_ram_gb:
+              type: number
+            db_disk_gb:
+              type: number
+            db_max_conns:
+              type: integer
+            cache_ram_mb:
+              type: number
+            storage_gb:
+              type: number
+            network_gb_per_month:
+              type: number
+            function_cpu_min_per_month:
+              type: integer
+              format: int64
+            log_ingest_gb_per_month:
+              type: number
+              description: Hard cap for original uncompressed managed-log ingestion per month.
+            baseline_yuan_per_hour:
+              type: number
+              description: Raw 100%-allocated Cell COGS before retail markup.
+            monthly_fee_yuan:
+              type: number
+              description: Actual fixed fee charged for the current spec; Nano is zero-rated by Free.
+            reference_monthly_list_price_yuan:
+              type: number
+              description: Cost-calibrated reference price before a plan inclusion such as Free Nano.
+            pricing_policy_version:
+              type: string
+        tier_caps:
+          deprecated: true
+          description: Compatibility alias for compute_spec_caps.
+          allOf:
+            - $ref: "#/components/schemas/ComputeSpecCaps"
+
+    ComputeSpecCaps:
+      type: object
+      properties:
+        capacity_units:
+          type: integer
+          format: int64
+        compute_vcpu_slot:
+          type: number
+        db_ram_gb:
+          type: number
+        db_disk_gb:
+          type: number
+        db_max_conns:
+          type: integer
+        cache_ram_mb:
+          type: number
+        storage_gb:
+          type: number
+        network_gb_per_month:
+          type: number
+        function_cpu_min_per_month:
+          type: integer
+          format: int64
+        log_ingest_gb_per_month:
+          type: number
+          description: Hard cap for original uncompressed managed-log ingestion per month.
+        baseline_yuan_per_hour:
+          type: number
+          description: Raw 100%-allocated Cell COGS before retail markup.
+        monthly_fee_yuan:
+          type: number
+        reference_monthly_list_price_yuan:
+          type: number
+        pricing_policy_version:
+          type: string
+
+    FunctionDeployRequest:
+      type: object
+      required: [source]
+      properties:
+        runtime:
+          type: string
+          default: node
+        source:
+          type: string
+          description: User code, max 256 KB.
+
+    FunctionView:
+      type: object
+      properties:
+        name:
+          type: string
+        runtime:
+          type: string
+
+    LogEntry:
+      type: object
+      required: [timestamp_ns, message]
+      properties:
+        timestamp_ns:
+          type: integer
+          format: int64
+          description: Provider-canonical Unix timestamp in nanoseconds.
+        message:
+          type: string
+        stream:
+          type: string
+          enum: [stdout, stderr, system]
+        request_id:
+          type: string
+          description: Provider invocation ID when one is available.
+
+    Bundle:
+      type: object
+      description: |
+        Reserved for future use — Mortar's compute primitive will expose
+        deployed-bundle metadata here when the function-deploy path
+        moves from inline source to a content-addressed bundle blob.
+      properties:
+        id:
+          type: string
+        sha256:
+          type: string
+        size_bytes:
+          type: integer
+          format: int64
+        created_at:
+          type: string
+          format: date-time
+
+    CronScheduleCreateRequest:
+      type: object
+      required: [name, function_name, cron]
+      properties:
+        name:
+          type: string
+          description: Stable schedule identifier (unique within tenant).
+        function_name:
+          type: string
+          description: Target compute function to invoke.
+        cron:
+          type: string
+          description: Standard 5-field cron expression (UTC).
+          example: "*/15 * * * *"
+        enabled:
+          type: boolean
+          default: true
+
+    CronSchedulePatchRequest:
+      type: object
+      required: [enabled]
+      properties:
+        enabled:
+          type: boolean
+
+    CronSchedule:
+      type: object
+      required: [name, function_name, cron, enabled, next_run_unix, last_run_unix]
+      properties:
+        name:
+          type: string
+        function_name:
+          type: string
+        cron:
+          type: string
+        enabled:
+          type: boolean
+        next_run_unix:
+          type: integer
+          format: int64
+        last_run_unix:
+          type: integer
+          format: int64
+
+    QueueEnqueueRequest:
+      type: object
+      required: [type]
+      properties:
+        type:
+          type: string
+          description: Job-type identifier matched by the registered worker.
+        payload:
+          description: Opaque JSON forwarded to the handler.
+        run_at:
+          type: string
+          format: date-time
+          description: RFC3339 timestamp; omit/empty for "now".
+        max_attempts:
+          type: integer
+          default: 3
+
+    Job:
+      type: object
+      required:
+        [id, type, status, run_at, max_attempts, attempt_count, created_at, updated_at]
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+        payload:
+          description: Opaque JSON.
+        status:
+          type: string
+          enum: [pending, running, completed, failed]
+        run_at:
+          type: string
+          format: date-time
+        max_attempts:
+          type: integer
+        attempt_count:
+          type: integer
+        last_error:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    AccountTokenCreateRequest:
+      type: object
+      required: [name]
+      properties:
+        name:
+          type: string
+          description: Human-readable label (e.g. "ci-deploy").
+        expires_in_days:
+          type: integer
+          minimum: 0
+          maximum: 365
+          description: Days until expiry; omit / 0 selects the one-year default. Values 1-365 choose a shorter fixed lifetime.
+
+    AccountTokenView:
+      type: object
+      required: [id, name, prefix, created_at, expires_at]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        prefix:
+          type: string
+          description: First 12 chars (e.g. `mtr_pat_a1bc`) — indexed lookup handle, safe to log.
+        created_at:
+          type: string
+          format: date-time
+        last_used_at:
+          type: string
+          format: date-time
+        expires_at:
+          type: string
+          format: date-time
+
+    AccountTokenCreated:
+      allOf:
+        - $ref: "#/components/schemas/AccountTokenView"
+        - type: object
+          required: [raw_key]
+          properties:
+            raw_key:
+              type: string
+              description: The unhashed PAT. Surfaced ONCE at creation; the server keeps only HMAC(raw_key).
+
+    CustomDomainCreateRequest:
+      type: object
+      required: [hostname]
+      properties:
+        hostname:
+          type: string
+
+    CustomDomain:
+      type: object
+      required: [hostname, project_id, verified, cert_status, created_at]
+      properties:
+        hostname:
+          type: string
+        project_id:
+          type: string
+        verified:
+          type: boolean
+        verified_at:
+          type: string
+          format: date-time
+        cert_status:
+          type: string
+          description: Lifecycle of the issued TLS cert (e.g. pending, issued).
+        txt_record:
+          type: string
+          description: Hostname to publish a TXT record under (e.g. `_mortar.example.com`).
+        txt_value:
+          type: string
+          description: The opaque verification token to set as the TXT value.
+        created_at:
+          type: string
+          format: date-time