openapi: 3.0.3
info:
  title: Ghost API
  version: 0.1.0
  description: Ghost database management API

servers:
  - url: https://api.ghost.build/v0
    description: Production

security:
  - BearerAuth: []

paths:
  # --- System ---

  /health:
    get:
      operationId: health
      summary: Health check
      description: Returns 200 OK if the service is healthy.
      security: []
      responses:
        "200":
          description: Service is healthy

  # --- Auth ---

  /auth/info:
    get:
      operationId: authInfo
      summary: Get authentication info
      description: Returns info about the authenticated API key.
      responses:
        "200":
          description: Authentication info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthInfo"
        default:
          $ref: "#/components/responses/Error"

  /auth/logout:
    post:
      operationId: logout
      summary: Log out
      description: |
        Logs the user out by revoking the given refresh token.
        Requires user authentication (JWT). API keys and project access tokens
        cannot be used with this endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LogoutRequest"
      responses:
        "204":
          description: Logged out successfully
        default:
          $ref: "#/components/responses/Error"

  # --- Spaces ---

  /spaces:
    get:
      operationId: listSpaces
      summary: List spaces
      description: |
        Returns Ghost spaces accessible to the authenticated user.
        For user JWTs, returns all Ghost spaces the user is a member of.
        For API keys, returns the single space the key is scoped to.
      responses:
        "200":
          description: List of spaces
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Space"
        default:
          $ref: "#/components/responses/Error"
    post:
      operationId: createSpace
      summary: Create a space
      description: |
        Creates a new Ghost space. Requires user authentication (JWT).
        API keys cannot be used to create spaces.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSpaceRequest"
      responses:
        "201":
          description: Space created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Space"
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/status:
    get:
      operationId: spaceStatus
      summary: Get space status
      description: Returns compute and storage usage for a space.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
      responses:
        "200":
          description: Space status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpaceStatus"
        default:
          $ref: "#/components/responses/Error"

  # --- API Keys ---

  /spaces/{space_id}/api_keys:
    get:
      operationId: listApiKeys
      summary: List API keys
      description: |
        Lists all API keys for the specified space.
        Requires user authentication (JWT). API keys cannot list other API keys.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
      responses:
        "200":
          description: List of API keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiKey"
        default:
          $ref: "#/components/responses/Error"
    post:
      operationId: createApiKey
      summary: Create an API key
      description: |
        Creates a new API key (client credentials) for the specified space.
        Requires user authentication (JWT). API keys cannot create other API keys.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateApiKeyRequest"
      responses:
        "201":
          description: API key created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyCredentials"
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/api_keys/{prefix}:
    delete:
      operationId: deleteApiKey
      summary: Delete an API key
      description: |
        Deletes an API key from the specified space.
        Requires user authentication (JWT). API keys cannot delete other API keys.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - $ref: "#/components/parameters/ApiKeyPrefix"
      responses:
        "204":
          description: API key deleted
        default:
          $ref: "#/components/responses/Error"

  # --- Databases ---

  /spaces/{space_id}/databases:
    get:
      operationId: listDatabases
      summary: List databases
      description: Lists all databases in a space.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
      responses:
        "200":
          description: List of databases
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DatabaseWithUsage"
        default:
          $ref: "#/components/responses/Error"
    post:
      operationId: createDatabase
      summary: Create a database
      description: Creates a new database in a space.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDatabaseRequest"
      responses:
        "202":
          description: Database created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Database"
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/databases/{database_ref}:
    get:
      operationId: getDatabase
      summary: Get a database
      description: Gets a single database by ID.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - $ref: "#/components/parameters/DatabaseRef"
      responses:
        "200":
          description: Database details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Database"
        default:
          $ref: "#/components/responses/Error"
    delete:
      operationId: deleteDatabase
      summary: Delete a database
      description: Deletes a database.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - $ref: "#/components/parameters/DatabaseRef"
      responses:
        "202":
          description: Database deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Database"
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/databases/{database_ref}/fork:
    post:
      operationId: forkDatabase
      summary: Fork a database
      description: Forks an existing database.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - $ref: "#/components/parameters/DatabaseRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ForkDatabaseRequest"
      responses:
        "202":
          description: Database forked
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Database"
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/databases/{database_ref}/pause:
    post:
      operationId: pauseDatabase
      summary: Pause a database
      description: Pauses a running database.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - $ref: "#/components/parameters/DatabaseRef"
      responses:
        "202":
          description: Database paused
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Database"
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/databases/{database_ref}/resume:
    post:
      operationId: resumeDatabase
      summary: Resume a database
      description: Resumes a paused database.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - $ref: "#/components/parameters/DatabaseRef"
      responses:
        "202":
          description: Database resumed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Database"
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/databases/{database_ref}/rename:
    post:
      operationId: renameDatabase
      summary: Rename a database
      description: Renames a database.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - $ref: "#/components/parameters/DatabaseRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RenameDatabaseRequest"
      responses:
        "204":
          description: Database renamed
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/databases/{database_ref}/password:
    post:
      operationId: updatePassword
      summary: Update database password
      description: Resets the database password.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - $ref: "#/components/parameters/DatabaseRef"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdatePasswordRequest"
      responses:
        "204":
          description: Password updated
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/databases/{database_ref}/logs:
    get:
      operationId: databaseLogs
      summary: Get database logs
      description: Gets database logs.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - $ref: "#/components/parameters/DatabaseRef"
        - name: page
          in: query
          required: false
          description: Zero-indexed page number for backward pagination. Page 0 returns the most recent logs; each successive page fetches older entries.
          schema:
            type: integer
        - name: until
          in: query
          required: false
          description: Return logs at or before this timestamp. Defaults to now.
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: Database logs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LogsResponse"
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/databases/{database_ref}/share:
    post:
      operationId: shareDatabase
      summary: Share a database
      description: Creates a shareable snapshot of a database. Returns a share token that can be used to create a new database from the snapshot in another space.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - $ref: "#/components/parameters/DatabaseRef"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ShareDatabaseRequest"
      responses:
        "201":
          description: Share created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DatabaseShare"
        default:
          $ref: "#/components/responses/Error"

  # --- Shares ---

  /spaces/{space_id}/shares:
    get:
      operationId: listShares
      summary: List database shares
      description: Lists all shared snapshots for a space.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
      responses:
        "200":
          description: List of shares
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DatabaseShare"
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/shares/{share_token}:
    delete:
      operationId: revokeShare
      summary: Revoke a database share
      description: Revokes a shared snapshot, deleting the underlying storage snapshot. The share is identified by its share token.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - name: share_token
          in: path
          required: true
          description: Share token returned from `listShares` or `shareDatabase` (begins with `gs_`).
          schema:
            type: string
            pattern: "^gs_[A-Za-z0-9_-]+$"
      responses:
        "200":
          description: Share revoked
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DatabaseShare"
        default:
          $ref: "#/components/responses/Error"

  # --- Billing ---

  /spaces/{space_id}/invoices:
    get:
      operationId: listInvoices
      summary: List invoices
      description: |
        Lists the most recent invoices for a space.
        Requires a user JWT; API keys are not authorized.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
      responses:
        "200":
          description: List of invoices
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvoicesResponse"
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/invoices/{invoice_id}:
    get:
      operationId: getInvoice
      summary: Get invoice detail
      description: |
        Returns the line-item breakdown for a single invoice, looked up by the
        invoice ID returned from `listInvoices`.
        Requires a user JWT; API keys are not authorized.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - name: invoice_id
          in: path
          required: true
          description: Invoice ID returned from `listInvoices`.
          schema:
            type: string
      responses:
        "200":
          description: Invoice detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvoiceDetail"
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/payment:
    get:
      operationId: listPaymentMethods
      summary: List payment methods
      description: Lists payment methods on file for a space.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
      responses:
        "200":
          description: List of payment methods
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentMethodsResponse"
        default:
          $ref: "#/components/responses/Error"
    post:
      operationId: createPaymentMethodSetup
      summary: Create payment method setup
      description: Creates a Stripe Setup Intent for payment method collection and returns the client secret and payment page URL.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
      responses:
        "200":
          description: Payment setup created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentSetupResponse"
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/payment/{payment_id}:
    get:
      operationId: getPaymentMethod
      summary: Get a payment method
      description: Returns a single payment method by ID.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - $ref: "#/components/parameters/PaymentId"
      responses:
        "200":
          description: Payment method
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentMethod"
        default:
          $ref: "#/components/responses/Error"
    delete:
      operationId: deletePaymentMethod
      summary: Delete a payment method
      description: Deletes a payment method.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - $ref: "#/components/parameters/PaymentId"
      responses:
        "204":
          description: Payment method deleted
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/payment/{payment_id}/primary:
    put:
      operationId: setPaymentMethodPrimary
      summary: Set primary payment method
      description: Sets a payment method as the primary payment method for the space.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - $ref: "#/components/parameters/PaymentId"
      responses:
        "204":
          description: Payment method set as primary
        default:
          $ref: "#/components/responses/Error"

  /spaces/{space_id}/payment/{payment_id}/deletion:
    delete:
      operationId: cancelPaymentMethodDeletion
      summary: Cancel pending payment method deletion
      description: Cancels a pending deletion for a payment method.
      parameters:
        - $ref: "#/components/parameters/SpaceId"
        - $ref: "#/components/parameters/PaymentId"
      responses:
        "204":
          description: Pending deletion cancelled
        default:
          $ref: "#/components/responses/Error"

  # --- Analytics ---

  /analytics/identify:
    post:
      operationId: analyticsIdentify
      summary: Identify user
      description: Identifies a user for analytics.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IdentifyRequest"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
        default:
          $ref: "#/components/responses/Error"

  /analytics/track:
    post:
      operationId: analyticsTrack
      summary: Track event
      description: Tracks an analytics event.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TrackRequest"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
        default:
          $ref: "#/components/responses/Error"

  # --- Feedback ---

  /feedback:
    post:
      operationId: submitFeedback
      summary: Submit feedback
      description: Submits feedback or bug report.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FeedbackRequest"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
        default:
          $ref: "#/components/responses/Error"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: "User JWT or API key token (e.g. `gt_...`) sent as `Authorization: Bearer <token>`."

  parameters:
    SpaceId:
      name: space_id
      in: path
      required: true
      description: Ghost space ID.
      schema:
        type: string
    DatabaseRef:
      name: database_ref
      in: path
      required: true
      description: Database ID or name.
      schema:
        type: string
    PaymentId:
      name: payment_id
      in: path
      required: true
      description: Payment method ID.
      schema:
        type: string
    ApiKeyPrefix:
      name: prefix
      in: path
      required: true
      description: API key prefix (e.g. `gt_...`).
      schema:
        type: string

  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:
    # --- Common ---

    Error:
      type: object
      description: Standard error response.
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable error message.

    StatusResponse:
      type: object
      description: Generic success response.
      required:
        - status
      properties:
        status:
          type: string
          description: Status string (e.g. `success`).

    # --- Auth ---

    AuthInfo:
      type: object
      description: Information about the authenticated caller.
      required:
        - type
      properties:
        type:
          type: string
          description: Type of authentication used.
          enum:
            - api_key
            - user
        api_key:
          $ref: "#/components/schemas/ApiKeyInfo"
        user:
          $ref: "#/components/schemas/UserInfo"

    UserInfo:
      type: object
      description: Authenticated user details.
      required:
        - id
        - email
        - name
      properties:
        id:
          type: string
          description: User ID.
        email:
          type: string
          description: User email address.
        name:
          type: string
          description: User's full name.

    ApiKeyInfo:
      type: object
      description: Information about the API key used for authentication.
      required:
        - space_id
        - space_name
        - user_id
        - user_email
        - user_name
      properties:
        space_id:
          type: string
          description: Space the API key is scoped to.
        space_name:
          type: string
          description: Name of the space the API key is scoped to.
        user_id:
          type: string
          description: ID of the user who created the API key.
        user_email:
          type: string
          description: Email of the user who created the API key.
        user_name:
          type: string
          description: Name of the user who created the API key.

    LogoutRequest:
      type: object
      required:
        - refreshToken
      properties:
        refreshToken:
          type: string
          description: Refresh token to revoke.

    # --- Spaces ---

    Space:
      type: object
      description: A Ghost space.
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: Space ID.
        name:
          type: string
          description: Space name.

    CreateSpaceRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name for the new space.

    SpaceStatus:
      type: object
      description: Space-level usage and cost for the current billing cycle.
      required:
        - storage_mib
        - storage_limit_mib
        - compute_minutes
        - compute_limit_minutes
      properties:
        storage_mib:
          type: integer
          format: int64
          description: Total storage used across all databases in the space, in MiB.
        storage_limit_mib:
          type: integer
          format: int64
          description: Storage quota for the space, in MiB.
        compute_minutes:
          type: integer
          format: int64
          description: Total compute minutes used across all databases in the space during the current billing cycle.
        compute_limit_minutes:
          type: integer
          format: int64
          description: Compute-minute quota for the space. When exceeded, all running databases in the space are automatically paused.
        cost_to_date:
          type: number
          format: double
          description: Gross cost accrued so far this billing cycle.
        estimated_total_cost:
          type: number
          format: double
          description: Projected gross total for the current billing cycle based on usage to date.
        billing_period_start:
          type: string
          format: date-time
          description: Start of the current billing cycle.
        billing_period_end:
          type: string
          format: date-time
          description: End of the current billing cycle.

    # --- API Keys ---

    ApiKey:
      type: object
      description: An API key in a space.
      required:
        - prefix
        - name
        - created_at
      properties:
        prefix:
          type: string
          description: Stable prefix identifier for the key (starts with `gt_`). Used to identify the key for deletion.
        name:
          type: string
          description: User-provided label for the key.
        created_at:
          type: string
          format: date-time
          description: Time the key was created.

    ApiKeyCredentials:
      type: object
      description: Credentials for a newly created API key. The secret portion cannot be retrieved again later.
      required:
        - api_key
        - access_key
        - secret_key
      properties:
        api_key:
          type: string
          description: "Bearer token for the key. Use as `Authorization: Bearer <api_key>`."
        access_key:
          type: string
          deprecated: true
          description: Use as the username in HTTP Basic auth.
        secret_key:
          type: string
          deprecated: true
          description: Use as the password in HTTP Basic auth.

    CreateApiKeyRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: User-provided label for the new API key.

    # --- Databases ---

    DatabaseType:
      type: string
      description: |
        Database deployment model.
        - `standard` — shared-resource databases subject to the space's compute and storage limits.
        - `dedicated` — per-instance paid databases with guaranteed resources, exempt from space-level auto-pause.
      enum:
        - standard
        - dedicated
      default: standard

    DatabaseSize:
      type: string
      description: Compute size for dedicated databases. Each step up allocates proportionally more vCPU and RAM.
      enum:
        - 1x
        - 2x
        - 4x
        - 8x

    DatabaseStatus:
      type: string
      description: Current lifecycle status of the database.
      enum:
        - queued
        - configuring
        - running
        - pausing
        - paused
        - resuming
        - deleting
        - deleted
        - upgrading
        - unstable
        - unknown

    Database:
      type: object
      description: A Ghost database.
      required:
        - id
        - name
        - type
        - status
        - host
        - port
      properties:
        id:
          type: string
          description: Database ID.
        name:
          type: string
          description: Database name. Unique within the space.
        type:
          $ref: "#/components/schemas/DatabaseType"
        size:
          $ref: "#/components/schemas/DatabaseSize"
          nullable: true
        status:
          $ref: "#/components/schemas/DatabaseStatus"
        host:
          type: string
          description: PostgreSQL hostname for connections.
        port:
          type: integer
          description: PostgreSQL port for connections.
        password:
          type: string
          nullable: true
          description: PostgreSQL password for the default user. Returned on every GET for authorized callers.
        storage_mib:
          type: integer
          nullable: true
          description: Current disk usage in MiB. Null if not yet available.

    DatabaseWithUsage:
      description: A Ghost database with current billing-cycle usage included.
      allOf:
        - $ref: "#/components/schemas/Database"
        - type: object
          properties:
            compute_minutes:
              type: integer
              format: int64
              nullable: true
              description: Compute minutes used by this database during the current billing cycle. Only populated for `standard` databases.

    CreateDatabaseRequest:
      type: object
      properties:
        name:
          type: string
          description: Name for the new database. Auto-generated if omitted.
        type:
          $ref: "#/components/schemas/DatabaseType"
        size:
          $ref: "#/components/schemas/DatabaseSize"
        share_token:
          type: string
          description: Share token from a database share (begins with `gs_`). When provided, creates the new database from the shared snapshot.

    ForkDatabaseRequest:
      type: object
      description: Request body for forking a database. Fields default to the source database's values when omitted.
      properties:
        name:
          type: string
          description: Name for the forked database. Auto-generated from the source name if omitted.
        type:
          $ref: "#/components/schemas/DatabaseType"
        size:
          $ref: "#/components/schemas/DatabaseSize"

    RenameDatabaseRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: New name for the database.

    UpdatePasswordRequest:
      type: object
      required:
        - password
      properties:
        password:
          type: string
          description: New PostgreSQL password for the default user.

    LogsResponse:
      type: object
      required:
        - logs
      properties:
        logs:
          type: array
          description: Log lines, most recent first.
          items:
            type: string

    # --- Shares ---

    DatabaseShare:
      type: object
      description: A shareable snapshot of a database. Can be used to create a new database from the snapshot in another space.
      required:
        - share_token
        - database_id
        - database_name
        - created_at
      properties:
        share_token:
          type: string
          description: Token passed to `createDatabase` (via `share_token`) to create a new database from the shared snapshot in another space. Also used to revoke the share via `revokeShare`. Always begins with `gs_`.
        database_id:
          type: string
          description: ID of the source database.
        database_name:
          type: string
          description: Name of the source database.
        created_at:
          type: string
          format: date-time
          description: Time the share was created.
        expires_at:
          type: string
          format: date-time
          description: Time the share expires. Absent if the share does not expire.
        revoked_at:
          type: string
          format: date-time
          description: Time the share was revoked. Absent if the share is still active.

    ShareDatabaseRequest:
      type: object
      description: Options for creating a database share.
      properties:
        expires_at:
          type: string
          format: date-time
          description: Time after which the share expires. If omitted, the share does not expire.

    # --- Billing ---

    InvoicesResponse:
      type: object
      required:
        - invoices
      properties:
        invoices:
          type: array
          description: Recent invoices, most recent first.
          items:
            $ref: "#/components/schemas/Invoice"

    Invoice:
      type: object
      description: Invoice summary.
      required:
        - id
        - invoice_number
        - invoice_date
        - total
        - status
      properties:
        id:
          type: string
          description: Opaque invoice ID used to look up invoice details.
        invoice_number:
          type: string
          description: Human-readable invoice number (e.g. "INV-12345").
        invoice_date:
          type: string
          format: date-time
          description: Date the invoice was issued.
        total:
          type: number
          format: double
          description: Invoice total.
        status:
          type: string
          enum: [paid, issued, delinquent]
          description: |
            Invoice status:
            - `paid` — invoice has been paid.
            - `issued` — invoice has been issued and is within its net-terms payment window (not yet paid, not yet delinquent).
            - `delinquent` — payment has failed and the invoice needs to be resolved by the user.

    InvoiceDetail:
      type: object
      description: Line-item breakdown of an invoice.
      required:
        - line_items
      properties:
        line_items:
          type: array
          description: Line items that make up the invoice.
          items:
            $ref: "#/components/schemas/InvoiceLineItem"

    InvoiceLineItem:
      type: object
      required:
        - product_type
        - quantity
        - unit_price
        - line_total
      properties:
        database_id:
          type: string
          description: Ghost database ID this line item is attributed to, if any.
        product_type:
          type: string
          description: "Product category (e.g. storage, compute)."
        detailed_spec:
          type: string
          description: Additional spec details (e.g. tier, size).
        quantity:
          type: number
          format: double
          description: Quantity billed. Units depend on `product_type`.
        unit_price:
          type: number
          format: double
          description: Price per unit of `quantity`.
        line_total:
          type: number
          format: double
          description: Total charge for this line (`quantity` × `unit_price`).

    PaymentMethod:
      type: object
      description: A payment method on file for a space.
      required:
        - id
        - primary
        - pending_deletion
        - brand
        - last4
        - exp_month
        - exp_year
      properties:
        id:
          type: string
          description: Payment method ID.
        primary:
          type: boolean
          description: True if this is the primary payment method for the space.
        pending_deletion:
          type: boolean
          description: True if deletion has been scheduled for this payment method. The deletion can be cancelled until processed.
        brand:
          type: string
          description: Card brand (e.g. `visa`, `mastercard`).
        last4:
          type: string
          description: Last four digits of the card number.
        exp_month:
          type: integer
          description: Card expiration month (1-12).
        exp_year:
          type: integer
          description: Card expiration year (four digits).

    PaymentMethodsResponse:
      type: object
      required:
        - payment_methods
      properties:
        payment_methods:
          type: array
          description: Payment methods on file for the space.
          items:
            $ref: "#/components/schemas/PaymentMethod"

    PaymentSetupResponse:
      type: object
      description: Stripe Setup Intent details for collecting a new payment method.
      required:
        - client_secret
        - payment_url
      properties:
        client_secret:
          type: string
          description: Stripe Setup Intent client secret.
        payment_url:
          type: string
          description: URL of the hosted payment page for collecting card details.

    # --- Analytics ---

    IdentifyRequest:
      type: object
      description: User properties to associate with the authenticated user in analytics.
      required:
        - properties
      properties:
        properties:
          type: object
          additionalProperties: true
          description: Free-form user properties.

    TrackRequest:
      type: object
      description: An analytics event to record.
      required:
        - event
      properties:
        event:
          type: string
          description: Event name.
        properties:
          type: object
          additionalProperties: true
          description: Free-form event properties.

    # --- Feedback ---

    FeedbackRequest:
      type: object
      description: User-submitted feedback or bug report.
      required:
        - message
        - source
        - version
        - os
      properties:
        message:
          type: string
          description: Feedback message from the user.
        source:
          type: string
          description: Source of the feedback request (e.g. `cli`, `mcp`).
        version:
          type: string
          description: Version of the client submitting the feedback.
        os:
          type: string
          description: Operating system of the client submitting the feedback.