openapi: 3.1.0
info:
  title: FormPostbox Developer API
  version: "1.0.0"
  description: |
    Read-only customer API for retained form submissions. Available to workspaces with an
    active Starter or Builder plan; every request re-checks the current paid entitlement.
    Independent of the browser session API and the Admin API: keys never authenticate
    browser or admin endpoints, and cookies never authenticate this API.

    Contract sources of truth: `src/server/developer-api/constants.ts` (limits, key format,
    pagination bounds) and `src/server/developer-api/handler.ts` (statuses and codes).
servers:
  - url: https://formpostbox.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Submissions
    description: Read submissions already received and still inside their retention period.
paths:
  /api/v1/submissions:
    get:
      operationId: listSubmissions
      summary: List retained submissions
      description: |
        Returns summaries ordered by `receivedAt` descending with a stable `receivedAt + id`
        tiebreak. The `summary` object is a truncated preview; use the detail endpoint for
        the complete submitted fields. Deleted records, cleared content, records past their
        deletion date, and closed accounts are never returned.
      parameters:
        - name: formId
          in: query
          required: false
          description: Restrict results to one form (UUID).
          schema: {type: string, format: uuid}
        - name: from
          in: query
          required: false
          description: |
            Inclusive UTC lower bound. `YYYY-MM-DD` (the whole UTC day from 00:00) or a UTC
            timestamp such as `2026-10-08T09:30:00Z`.
          schema: {type: string}
        - name: to
          in: query
          required: false
          description: |
            Exclusive UTC upper bound. A date-only value covers the whole UTC day.
          schema: {type: string}
        - name: limit
          in: query
          required: false
          description: Page size.
          schema: {type: integer, minimum: 1, maximum: 100, default: 25}
        - name: cursor
          in: query
          required: false
          description: |
            Opaque cursor from `nextCursor`. Keep the same filters while paging; a cursor is
            rejected with `invalid_cursor` when filters change.
          schema: {type: string, maxLength: 256}
      responses:
        "200":
          description: One page of submission summaries.
          headers:
            Cache-Control: {schema: {type: string, const: no-store}}
          content:
            application/json:
              schema:
                type: object
                required: [data, hasMore, nextCursor]
                properties:
                  data:
                    type: array
                    items: {$ref: "#/components/schemas/SubmissionSummary"}
                  hasMore: {type: boolean}
                  nextCursor:
                    type: [string, "null"]
        "400": {$ref: "#/components/responses/InvalidRequest"}
        "401": {$ref: "#/components/responses/InvalidKey"}
        "403": {$ref: "#/components/responses/PlanRequired"}
        "405": {$ref: "#/components/responses/MethodNotAllowed"}
        "429": {$ref: "#/components/responses/RateLimited"}
        "503": {$ref: "#/components/responses/Unavailable"}
  /api/v1/submissions/{submissionId}:
    get:
      operationId: getSubmission
      summary: Get one submission with complete fields
      parameters:
        - name: submissionId
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        "200":
          description: The complete submission.
          headers:
            Cache-Control: {schema: {type: string, const: no-store}}
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: {$ref: "#/components/schemas/SubmissionDetail"}
        "400": {$ref: "#/components/responses/InvalidRequest"}
        "401": {$ref: "#/components/responses/InvalidKey"}
        "403": {$ref: "#/components/responses/PlanRequired"}
        "404": {$ref: "#/components/responses/NotFound"}
        "405": {$ref: "#/components/responses/MethodNotAllowed"}
        "429": {$ref: "#/components/responses/RateLimited"}
        "503": {$ref: "#/components/responses/Unavailable"}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        A workspace API key created in Workspace → Developers. The key is displayed once and
        stored server-side as a SHA-256 hash only. It carries the fixed `submissions:read`
        scope and expires 365 days after creation.
  responses:
    InvalidRequest:
      description: Invalid parameter, filter context, or cursor.
      headers:
        Cache-Control: {schema: {type: string, const: no-store}}
      content:
        application/json:
          schema: {$ref: "#/components/schemas/Error"}
          examples:
            badParameter:
              value: {error: "Enter limit as a whole number between 1 and 100.", code: invalid_request}
            badCursor:
              value: {error: "This pagination cursor is invalid.", code: invalid_cursor}
    InvalidKey:
      description: Missing, malformed, revoked, or expired key, or a closed account.
      headers:
        Cache-Control: {schema: {type: string, const: no-store}}
        WWW-Authenticate: {schema: {type: string, const: Bearer}}
      content:
        application/json:
          schema: {$ref: "#/components/schemas/Error"}
          examples:
            invalidKey:
              value: {error: "Missing or invalid API key.", code: invalid_key}
    PlanRequired:
      description: The workspace has no current paid entitlement.
      headers:
        Cache-Control: {schema: {type: string, const: no-store}}
      content:
        application/json:
          schema: {$ref: "#/components/schemas/Error"}
          examples:
            planRequired:
              value: {error: "The Developer API is available on the Starter and Builder plans.", code: plan_required}
    NotFound:
      description: Unknown route, or a record that is missing, outside this workspace, or past retention.
      headers:
        Cache-Control: {schema: {type: string, const: no-store}}
      content:
        application/json:
          schema: {$ref: "#/components/schemas/Error"}
          examples:
            notFound:
              value: {error: "Not found.", code: not_found}
    RateLimited:
      description: Rate limit reached. Wait for the seconds in `Retry-After` before retrying.
      headers:
        Cache-Control: {schema: {type: string, const: no-store}}
        Retry-After: {schema: {type: integer}, description: Seconds to wait before retrying.}
      content:
        application/json:
          schema: {$ref: "#/components/schemas/Error"}
          examples:
            rateLimited:
              value: {error: "Too many requests. Please try again later.", code: rate_limit}
    MethodNotAllowed:
      description: Only GET is supported. The response carries `Allow: GET`.
      headers:
        Allow: {schema: {type: string, const: GET}}
        Cache-Control: {schema: {type: string, const: no-store}}
      content:
        application/json:
          schema: {$ref: "#/components/schemas/Error"}
          examples:
            methodNotAllowed:
              value: {error: "Method not allowed.", code: method_not_allowed}
    Unavailable:
      description: Temporary condition or resource contention; retry later.
      headers:
        Cache-Control: {schema: {type: string, const: no-store}}
      content:
        application/json:
          schema: {$ref: "#/components/schemas/Error"}
          examples:
            unavailable:
              value: {error: "The service is temporarily unavailable. Please try again.", code: unavailable}
  schemas:
    Error:
      type: object
      required: [error, code]
      properties:
        error: {type: string}
        code: {type: string}
    SubmissionBase:
      type: object
      required: [id, formId, formName, siteName, receivedAt, retentionEndsAt, reviewed, notificationStatus]
      properties:
        id: {type: string, format: uuid}
        formId: {type: [string, "null"], format: uuid}
        formName: {type: string}
        siteName: {type: string}
        receivedAt: {type: string, format: date-time, description: UTC ISO 8601.}
        retentionEndsAt: {type: string, format: date-time, description: Current guaranteed retention date in UTC ISO 8601. Verified continuous Builder renewals may extend it. After Builder ends the deadline is at least one calendar year after receipt and 30 days after Builder access ends. Expired or deleted content cannot be restored.}
        reviewed: {type: boolean}
        notificationStatus:
          type: [string, "null"]
          description: Latest provider notification status (for example off, queued, sent, delivered, failed). Null on summaries, or "off", means the form had email notifications turned off when this submission was received; the message is saved in the inbox only.
    SubmissionSummary:
      allOf:
        - $ref: "#/components/schemas/SubmissionBase"
        - type: object
          required: [summary]
          properties:
            summary:
              type: object
              required: [title, preview]
              description: Truncated preview only. Fetch the detail endpoint for complete fields.
              properties:
                title: {type: string}
                preview: {type: string}
    SubmissionDetail:
      allOf:
        - $ref: "#/components/schemas/SubmissionBase"
        - type: object
          required: [fields]
          properties:
            fields:
              type: object
              additionalProperties: {type: string}
              description: The complete submitted field map, exactly as received.
