Emboss Account API

openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
paths:
  /forms/quote:
    post:
      summary: Account Quote
      operationId: account_quote_forms_quote_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_account_quote_forms_quote_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms:
    post:
      summary: Create Form
      operationId: create_form_forms_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_create_form_forms_post'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormCreated'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      summary: List Forms
      operationId: list_forms_forms_get
      parameters:
      - name: states
        in: query
        required: false
        schema:
          enum:
          - ready
          - all
          type: string
          default: ready
          title: States
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 100
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormsListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/{form_id}:
    get:
      summary: Get Form
      operationId: get_form_forms__form_id__get
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormStatus'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      summary: Delete Form
      description: 'Spec 2.3: the documents go first, under every policy, then the row is soft

        deleted. A form with work still running answers 409 rather than deleting

        blobs out from under it.'
      operationId: delete_form_forms__form_id__delete
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/{form_id}/contract:
    get:
      summary: Get Contract
      operationId: get_contract_forms__form_id__contract_get
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /usage:
    get:
      summary: Get Usage
      operationId: get_usage_usage_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
  /forms/{form_id}/fillable:
    get:
      summary: Get Fillable
      operationId: get_fillable_forms__form_id__fillable_get
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/{form_id}/thumbnail:
    get:
      summary: Get Thumbnail
      operationId: get_thumbnail_forms__form_id__thumbnail_get
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sessions:
    post:
      summary: Create Session
      operationId: create_session_sessions_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreate'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sessions/{sid}:
    get:
      summary: Get Session
      operationId: get_session_sessions__sid__get
      parameters:
      - name: sid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Sid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sessions/{sid}/fields:
    put:
      summary: Put Fields
      operationId: put_fields_sessions__sid__fields_put
      parameters:
      - name: sid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Sid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sessions/{sid}/fill:
    post:
      summary: Fill
      operationId: fill_sessions__sid__fill_post
      parameters:
      - name: sid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Sid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sessions/{sid}/pdf:
    get:
      summary: Session Pdf
      operationId: session_pdf_sessions__sid__pdf_get
      parameters:
      - name: sid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Sid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/with-context:
    post:
      summary: Create With Context
      operationId: create_with_context_forms_with_context_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_create_with_context_forms_with_context_post'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextJobCreated'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/{form_id}/with-context:
    post:
      summary: Fill Existing With Context
      description: 'Standalone fill-from-context: fill an already-extracted form the caller

        owns from context. Bills ONE with_context event (no re-extraction). The

        form already exists, so `retention` is accepted for symmetry with the

        other routes and validated, but otherwise ignored: the form''s own policy

        (set at creation) is what governs it.'
      operationId: fill_existing_with_context_forms__form_id__with_context_post
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_fill_existing_with_context_forms__form_id__with_context_post'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextJobCreated'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/with-context/{job_id}:
    get:
      summary: Get With Context
      operationId: get_with_context_forms_with_context__job_id__get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextJobStatus'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/{form_id}/prepare:
    post:
      summary: Prepare Existing
      description: 'Prepare an already-extracted form the caller owns: one with_context event,

        a proposal instead of a rendered PDF. The form already exists, so `retention`

        is accepted for symmetry and validated, but otherwise ignored: the form''s own

        policy (set at creation) is what governs it.'
      operationId: prepare_existing_forms__form_id__prepare_post
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_prepare_existing_forms__form_id__prepare_post'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextJobCreated'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/prepare:
    post:
      summary: Prepare New
      description: 'Extract a fresh PDF and prepare it in one call: create + with_context.'
      operationId: prepare_new_forms_prepare_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_prepare_new_forms_prepare_post'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextJobCreated'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /proposals/{proposal_id}/commit:
    post:
      summary: Commit
      operationId: commit_proposals__proposal_id__commit_post
      parameters:
      - name: proposal_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Proposal Id
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextJobCreated'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $defs:
                CommitValue:
                  description: 'One caller decision. A null value SKIPS the field (a deliberate blank),

                    which is not the same as omitting it (leave whatever the proposal holds).'
                  properties:
                    field_id:
                      title: Field Id
                      type: integer
                    value:
                      title: Value
                    note:
                      anyOf:
                      - type: string
                      - type: 'null'
                      title: Note
                  required:
                  - field_id
                  title: CommitValue
                  type: object
              properties:
                values:
                  default: []
                  items:
                    $ref: '#/$defs/CommitValue'
                  title: Values
                  type: array
                confirm:
                  default: []
                  items:
                    type: integer
                  title: Confirm
                  type: array
                policy:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Policy
                idempotency_key:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Idempotency Key
                package:
                  default: false
                  title: Package
                  type: boolean
              title: CommitRequest
              type: object
  /proposals/{proposal_id}:
    get:
      summary: Get Proposal
      description: 'The proposal as its holder reads it. Lives here rather than in

        proposals.py because it shares this module''s auth rule exactly: the owner, or

        an anonymous pay-door payer holding a token minted for THIS proposal. That

        second case is why it cannot sit on the proposals router, which app.py mounts

        behind a blanket require_owner.


        A token-bearing read gets the token echoed back as commit_token, so the same

        response an owner reads carries, for a payer, the credential they commit with.

        An owner never sees the field: their API key already is their proof.'
      operationId: get_proposal_proposals__proposal_id__get
      parameters:
      - name: proposal_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Proposal Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProposalResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /proposals/{proposal_id}/receipt:
    get:
      summary: Receipt
      operationId: receipt_proposals__proposal_id__receipt_get
      parameters:
      - name: proposal_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Proposal Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /proposals/{proposal_id}/pdf:
    get:
      summary: Commit Pdf
      operationId: commit_pdf_proposals__proposal_id__pdf_get
      parameters:
      - name: proposal_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Proposal Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/{form_id}/verify:
    post:
      summary: Verify Filled Pdf
      description: 'Verify a filled PDF the caller already holds against this form''s contract.


        Standalone because the caller may have rendered elsewhere, or filled by hand,

        and still wants the machine-readable answer to "is this document done". No

        model call: the same extraction.verify.check a commit runs, on a state read

        back out of the uploaded document.


        This router carries no require_owner dependency (commit authorises itself, so

        it must accept proposal tokens), so this route calls require_owner directly.

        Verify is owner-only: there is no proposal here to bear a token.


        request.state.owner already set is treated as pre-authorised, same as

        _authorise above: MCP''s owner_request and A2A''s _fake_request splice a

        resolved owner onto a request-shaped object before calling this route

        function directly and carry no real bearer credentials of their own for

        require_owner to read.'
      operationId: verify_filled_pdf_forms__form_id__verify_post
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_verify_filled_pdf_forms__form_id__verify_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /proposals/{proposal_id}/attachments:
    post:
      summary: Add Attachment
      operationId: add_attachment_proposals__proposal_id__attachments_post
      parameters:
      - name: proposal_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Proposal Id
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_add_attachment_proposals__proposal_id__attachments_post'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /proposals/{proposal_id}/attachments/{n}:
    delete:
      summary: Remove Attachment
      operationId: remove_attachment_proposals__proposal_id__attachments__n__delete
      parameters:
      - name: proposal_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Proposal Id
      - name: n
        in: path
        required: true
        schema:
          type: integer
          title: N
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/{form_id}/preview-fill:
    post:
      summary: Preview Fill
      operationId: preview_fill_forms__form_id__preview_fill_post
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          title: Form Id
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_preview_fill_forms__form_id__preview_fill_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewFillResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/{form_id}/suggest-mapping:
    post:
      summary: Suggest Mapping Endpoint
      operationId: suggest_mapping_endpoint_forms__form_id__suggest_mapping_post
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_suggest_mapping_endpoint_forms__form_id__suggest_mapping_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingSuggestion'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/{form_id}/fill-batch:
    post:
      summary: Fill Batch
      description: 'on_row: optional async (batch_id, row_number, total, result_dict) callback,

        threaded straight into _run_batch (see its own docstring). None for every

        FastAPI-routed call (REST''s own request body has no such field -- this is a

        plain extra kwarg, not a Form()/Body() field, so it is never bound from the

        wire); the A2A executor is the only caller that passes one, by calling this

        function directly as a Python coroutine rather than through routing.


        `retention`: the form already exists, so this is accepted for symmetry

        with the other routes and validated, but otherwise ignored: the form''s

        own policy (set at creation) is what governs it. Checked with

        isinstance(str), not `is not None`: fill_batch is also called directly as

        a plain coroutine (quotes.py''s execute_quote resume, accounts.py''s

        admin_fill_batch), bypassing FastAPI''s own request parsing -- there, an

        omitted `retention` kwarg leaves the parameter at its literal default,

        the Form(None) marker object itself, not None (mirrors why `on_row`

        above uses a plain None default rather than a Form marker).'
      operationId: fill_batch_forms__form_id__fill_batch_post
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      - name: on_row
        in: query
        required: false
        schema:
          title: On Row
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_fill_batch_forms__form_id__fill_batch_post'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCreated'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/fill-batch/{batch_id}:
    get:
      summary: Batch Status
      operationId: batch_status_forms_fill_batch__batch_id__get
      parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Batch Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatus'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/fill-batch/{batch_id}/rows/{n}/pdf:
    get:
      summary: Batch Row Pdf
      operationId: batch_row_pdf_forms_fill_batch__batch_id__rows__n__pdf_get
      parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Batch Id
      - name: n
        in: path
        required: true
        schema:
          type: integer
          title: N
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forms/fill-batch/{batch_id}/zip:
    get:
      summary: Batch Zip
      operationId: batch_zip_forms_fill_batch__batch_id__zip_get
      parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Batch Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fax:
    post:
      summary: Send Fax
      description: 'POST /fax: multipart (`to` + one or more PDF `files`, sent as one fax) or

        JSON ({"to", then exactly one of "job_id", "form_id", "pdf_url",

        "pdf_base64"}). JSON references resolve to the owner''s stored PDF through

        service/fax_source.py; multipart bytes go straight to the fax service.


        Honours Idempotency-Key (plan 2 task 5): a client-side retry with the same

        key replays the original job''s response instead of submitting a second

        fax. Independent of (and in addition to) create_fax_job''s own artifact+

        destination dedupe window, which catches a retry that used a fresh

        Idempotency-Key or none at all.'
      operationId: send_fax_fax_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                to:
                  type: string
                  description: Destination fax number, in E.164 form.
                files:
                  items:
                    type: string
                    format: binary
                  type: array
                  description: One or more PDFs, faxed as a single combined document.
              type: object
              required:
              - to
              - files
          application/json:
            schema:
              properties:
                to:
                  type: string
                  description: Destination fax number, in E.164 form.
                sources:
                  items:
                    properties:
                      artifact_id:
                        type: string
                        description: A prior artifact's id.
                      artifact_token:
                        type: string
                        description: The capability token for an anonymous artifact_id.
                      pages:
                        type: string
                        description: An optional page range, such as 1-3,7.
                    type: object
                    required:
                    - artifact_id
                  type: array
                  maxItems: 20
                  description: A list of prior artifacts, faxed together as one packet.
                artifact_id:
                  type: string
                  description: A prior artifact's id.
                artifact_token:
                  type: string
                  description: The capability token for an anonymous artifact_id.
                job_id:
                  type: string
                  description: A ready context/fill job's id.
                form_id:
                  type: string
                  description: A ready form's id.
                pdf_url:
                  type: string
                  description: A URL to fetch the PDF from.
                pdf_base64:
                  type: string
                  description: The PDF, base64-encoded.
              type: object
              required:
              - to
              description: Send exactly one of sources, artifact_id, job_id, form_id, pdf_url, or pdf_base64; it resolves to the caller's stored PDF.
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /fax/{job_id}:
    get:
      summary: Get Fax
      operationId: get_fax_fax__job_id__get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /artifacts/{artifact_id}:
    get:
      summary: Get Artifact
      operationId: get_artifact_artifacts__artifact_id__get
      parameters:

# --- truncated at 32 KB (135 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/getemboss-ai/refs/heads/main/openapi/getemboss-ai-account-openapi.yml