openapi: 3.2.0
info:
  title: Fast Admin API
  version: 0.1.0
security:
- bearer: []
- oauth2:
  - forms:read
  - forms:write
tags:
- name: Admin
paths:
  /admin/account:
    get:
      summary: Admin Get Account
      description: 'The account page''s own row: who this owner is, and the retention default

        every form they create afterwards inherits (spec section 3). Admin-gated with

        an owner param, like every other route on this router; the dashboard reads its

        signed-in user''s owner here.'
      operationId: admin_get_account_admin_account_get
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
    patch:
      summary: Admin Patch Account
      description: 'Flip the account default. Affects forms created afterwards only: an

        existing form keeps the policy it was created with.'
      operationId: admin_patch_account_admin_account_patch
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/usage:
    get:
      summary: Admin Usage
      description: 'Admin-only: usage for an arbitrary owner (the dashboard reads its logged-in

        user''s owner here). Whole router is behind require_admin. Mirrors the product

        GET /usage shape, but takes owner as a query param instead of the api-key state.'
      operationId: admin_usage_admin_usage_get
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/usage/detail:
    get:
      summary: Admin Usage Detail
      operationId: admin_usage_detail_admin_usage_detail_get
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      - name: month
        in: query
        required: true
        schema:
          type: string
          title: Month
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/billing/breakdown:
    get:
      summary: Admin Billing Breakdown
      operationId: admin_billing_breakdown_admin_billing_breakdown_get
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      - name: month
        in: query
        required: true
        schema:
          type: string
          title: Month
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingBreakdownResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/forms:
    get:
      summary: Admin Forms
      operationId: admin_forms_admin_forms_get
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Q
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 12
          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'
      tags:
      - Admin
    post:
      summary: Admin Create Form
      description: 'Admin act-as-owner create-fillable-form (the batch-fill web page). Delegates to

        the owner-scoped forms.create_form, which reads request.state.owner for billing +

        ownership.'
      operationId: admin_create_form_admin_forms_post
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_admin_create_form_admin_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'
      tags:
      - Admin
  /admin/forms/batch-runs:
    get:
      summary: Admin Batch Runs
      operationId: admin_batch_runs_admin_forms_batch_runs_get
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          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/BatchRunsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/forms/batch-counts:
    get:
      summary: Admin Batch Counts
      operationId: admin_batch_counts_admin_forms_batch_counts_get
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCountsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/layouts:
    get:
      summary: Admin Layouts
      description: 'The reuse readout for shared form_layouts rows: kind, hits, page count,

        match_baseline, title and timestamps. The table carries no owner or form

        id, so there is nothing here to scope or leak. match_baseline is the

        per-row loose bar (spec 1.4): an operator reading a row with many

        loose_hits and a low baseline is looking at the one shape of row worth

        checking by hand.'
      operationId: admin_layouts_admin_layouts_get
      parameters:
      - name: top
        in: query
        required: false
        schema:
          type: integer
          default: 20
          title: Top
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/forms/{form_id}:
    delete:
      summary: Admin Delete Form
      operationId: admin_delete_form_admin_forms__form_id__delete
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
    get:
      summary: Admin Form Status
      description: 'Admin act-as-owner form status poll. Delegates to owner-scoped forms.get_form

        (which owner-scopes via request.state.owner / owned_or_404).'
      operationId: admin_form_status_admin_forms__form_id__get
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      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'
      tags:
      - Admin
  /admin/forms/{form_id}/thumbnail:
    get:
      summary: Admin Form Thumbnail
      operationId: admin_form_thumbnail_admin_forms__form_id__thumbnail_get
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          title: Form Id
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/usage/trend:
    get:
      summary: Admin Usage Trend
      operationId: admin_usage_trend_admin_usage_trend_get
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      - name: days
        in: query
        required: false
        schema:
          type: integer
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageTrendResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/usage/events:
    get:
      summary: Admin Usage Events
      operationId: admin_usage_events_admin_usage_events_get
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      - name: range
        in: query
        required: false
        schema:
          type: string
          default: 24h
          title: Range
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          title: Page
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Page Size
      - name: kinds
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Kinds
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/forms/with-context:
    post:
      summary: Admin Create With Context
      description: 'Admin act-as-owner context fill (the /fill web page). Runs the owner''s

        billing gate; meters one with_context event for that owner.'
      operationId: admin_create_with_context_admin_forms_with_context_post
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_admin_create_with_context_admin_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'
      tags:
      - Admin
  /admin/forms/with-context/{job_id}:
    get:
      summary: Admin Context Status
      operationId: admin_context_status_admin_forms_with_context__job_id__get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      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'
      tags:
      - Admin
  /admin/forms/with-context/{job_id}/render:
    post:
      summary: Admin Context Render
      operationId: admin_context_render_admin_forms_with_context__job_id__render_post
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/forms/with-context/{job_id}/pdf:
    get:
      summary: Admin Context Pdf
      operationId: admin_context_pdf_admin_forms_with_context__job_id__pdf_get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/forms/{form_id}/with-context:
    post:
      summary: Admin Fill Existing
      description: 'Admin act-as-owner standalone fill: fill an existing ready form owned by

        `owner` from context. Bills one with_context event.'
      operationId: admin_fill_existing_admin_forms__form_id__with_context_post
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_admin_fill_existing_admin_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'
      tags:
      - Admin
  /admin/web-token/limits:
    get:
      summary: Admin Web Token Limits
      description: The engine's upload limits, so the website never hardcodes a number.
      operationId: admin_web_token_limits_admin_web_token_limits_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebTokenLimitsResponse'
      tags:
      - Admin
  /admin/web-token:
    post:
      summary: Admin Mint Web Token
      description: 'Mint a 15-minute, refresh-less web token so the signed-in browser can

        upload straight to the owner routes (spec 2026-09-09-web-direct-upload).

        The plaintext is returned once and never logged.'
      operationId: admin_mint_web_token_admin_web_token_post
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebTokenResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/forms/{form_id}/suggest-mapping:
    post:
      summary: Admin Suggest Mapping
      description: 'Admin act-as-owner spreadsheet->field mapping suggestion (the batch-fill web

        page). Delegates to the owner-scoped batch.suggest_mapping_endpoint, which reads

        request.state.owner for owner-scoping + with_context metering. admin_acting skips

        the anti-abuse rate limit; billing still applies. This 2-segment route cannot be

        shadowed by the 1-segment /admin/forms/{form_id} above.'
      operationId: admin_suggest_mapping_admin_forms__form_id__suggest_mapping_post
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_admin_suggest_mapping_admin_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'
      tags:
      - Admin
  /admin/forms/{form_id}/fill-batch:
    post:
      summary: Admin Fill Batch
      description: 'Admin act-as-owner batch fill (the batch-fill web page). Delegates to the

        owner-scoped batch.fill_batch, which reads request.state.owner for owner-scoping

        (owned_or_404), billing (standard_fill per row), and per-row metering. admin_acting

        skips the anti-abuse rate limit; billing still applies. This 2-segment route cannot

        be shadowed by the 1-segment /admin/forms/{form_id} above.'
      operationId: admin_fill_batch_admin_forms__form_id__fill_batch_post
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Form Id
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_admin_fill_batch_admin_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'
      tags:
      - Admin
  /admin/forms/fill-batch/{batch_id}:
    get:
      summary: Admin Batch Status
      description: 'Admin act-as-owner batch-fill status poll (the batch-fill web page). Delegates

        to the owner-scoped batch.batch_status, which owner-scopes via request.state.owner

        (owned_or_404). `fill-batch` is a static segment so this cannot be shadowed by the

        1-segment /admin/forms/{form_id} route above. No rate limit/billing on this GET;

        admin_acting set for uniformity with the other admin act-as-owner routes.'
      operationId: admin_batch_status_admin_forms_fill_batch__batch_id__get
      parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Batch Id
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      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'
      tags:
      - Admin
  /admin/forms/fill-batch/{batch_id}/zip:
    get:
      summary: Admin Batch Zip
      description: 'Admin act-as-owner batch-fill zip download (the batch-fill web page). Delegates

        to the owner-scoped batch.batch_zip, which owner-scopes via request.state.owner

        (owned_or_404). `fill-batch` is a static segment so this cannot be shadowed by the

        1-segment /admin/forms/{form_id} route above. No rate limit/billing on this GET;

        admin_acting set for uniformity with the other admin act-as-owner routes.'
      operationId: admin_batch_zip_admin_forms_fill_batch__batch_id__zip_get
      parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Batch Id
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/billing/setup-intent:
    post:
      summary: Admin Billing Setup Intent
      operationId: admin_billing_setup_intent_admin_billing_setup_intent_post
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupIntentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/billing/payment-method:
    get:
      summary: Admin Billing Payment Method
      operationId: admin_billing_payment_method_admin_billing_payment_method_get
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/billing/invoices:
    get:
      summary: Admin Billing Invoices
      operationId: admin_billing_invoices_admin_billing_invoices_get
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/billing/confirm:
    post:
      summary: Admin Billing Confirm
      operationId: admin_billing_confirm_admin_billing_confirm_post
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          title: Owner
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/billing/run-invoicing:
    post:
      summary: Admin Run Invoicing
      description: 'Admin-gated monthly billing run. Idempotent (billing_runs claim) + safe by default

        (preview unless BILLING_ENABLED and not dry_run). Per-owner isolation: one owner''s error

        becomes {status:''error''} and the batch continues.'
      operationId: admin_run_invoicing_admin_billing_run_invoicing_post
      parameters:
      - name: period
        in: query
        required: true
        schema:
          type: string
          title: Period
      - name: owner
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Owner
      - name: dry_run
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Dry Run
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/nudges/run:
    post:
      summary: Admin Run Nudges
      description: 'Admin-gated hourly nudge run. Idempotent per (owner, kind) via nudges_sent; dry_run

        lists who would be emailed and claims nothing. Also doubles as the nightly maintenance

        tick: purges expired OAuth rows (download links, codes, stale pending grants),

        terminal a2a_tasks rows older than 30 days (the A2A server''s own retention policy,

        service/a2a_store.py''s purge_expired), expired x402 quotes plus their staged

        R2 objects (service/quotes.py''s purge_expired_quotes), and ownerless proposals

        that expired before their caller ever committed (service/commits.py''s

        auto_commit_expired, so a paid anonymous prepare still ends in a file under

        its named policy) before the nudge pass runs, each step best-effort so one

        purge failure never blocks the others or nudges.'
      operationId: admin_run_nudges_admin_nudges_run_post
      parameters:
      - name: owner
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Owner
      - name: dry_run
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Dry Run
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/retention/sweep:
    post:
      summary: Admin Retention Sweep
      description: 'Admin-gated maintenance tick (spec 2.5 retention; send_fax spec section 9):

        called every ten minutes by the emboss-retention-cron Railway service. Runs the

        ephemeral-retention sweep, then the fax timeout sweep and the fax artifact

        reaper, each fail-soft. dry_run lists what is due and touches nothing.'
      operationId: admin_retention_sweep_admin_retention_sweep_post
      parameters:
      - name: dry_run
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Dry Run
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 200
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/library/{slug}/store:
    post:
      summary: Admin Library Store
      description: 'Store one fetched copy. Called by scripts/seed_library.py, which does the

        fetching: this process never reaches a government site, so the network

        policy for the seed lives in one script rather than in the service.


        `page_count` is ACCEPTED AND IGNORED. The seed script still sends it, so

        dropping the field would 422 a caller that is otherwise correct, but the

        route parses the bytes itself and stores what it read. The only two facts

        the caller supplies that this route trusts are the slug and the revision

        label, and the revision is a label for a person, never a decision input.'
      operationId: admin_library_store_admin_library__slug__store_post
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_admin_library_store_admin_library__slug__store_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/library/check:
    post:
      summary: Admin Library Check
      description: 'The weekly freshness check. Re-fetches every catalogue URL, compares the

        hash with the active row, writes one library_checks row each, and changes

        NOTHING that is served.'
      operationId: admin_library_check_admin_library_check_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Admin
  /admin/library:
    get:
      summary: Admin Library
      description: 'Every catalogue form with its active revision and last check status. A

        slug that has never been seeded shows a null revision, which is the readout

        that says a seed run is owed.'
      operationId: admin_library_admin_library_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Admin
  /admin/library/misses:
    get:
      summary: Admin Library Misses
      description: 'The searches that found nothing, most frequent first: the list of forms

        people wanted that the library does not have.'
      operationId: admin_library_misses_admin_library_misses_get
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/library/{slug}/accept:
    post:
      summary: Admin Library Accept
      description: 'Accept a changed form: fetch again, store the new copy, make it active,

        run make-fillable on it, and keep the old row inactive rather than deleting

        it, so a form filed against the previous revision can still be explained.'
      operationId: admin_library_accept_admin_library__slug__accept_post
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/oauth/pending/{pid}:
    get:
      summary: Pending
      operationId: pending_admin_oauth_pending__pid__get
      parameters:
      - name: pid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Pid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/oauth/consent:
    post:
      summary: Consent
      operationId: consent_admin_oauth_consent_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/oauth/grants:
    get:
      summary: Grants
      operationId: grants_admin_oauth_grants_get
      parameters:
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/oauth/clients:
    get:
      summary: Clients Since
      description: 'Registrations since a date (default seven days), for the acquisition

        report: which directories, gateways and reviewers have connected. Only

        names, sites, redirect hosts, source, time and a grant count leave.'
      operationId: clients_since_admin_oauth_clients_get
      parameters:
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Since
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/oauth/grants/{gid}:
    delete:
      summary: Revoke Grant
      operationId: revoke_grant_admin_oauth_grants__gid__delete
      parameters:
      - name: gid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Gid
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
components:
  schemas:
    WebTokenResponse:
      properties:
        api_base:
          type: string
          title: Api Base
        limits:
          $ref: '#/components/schemas/UploadLimits'
        access_token:
          type: string
          title: Access Token
        expires_in:
          type: integer
          title: Expires In
      type: object
      required:
      - api_base
      - limits
      - access_token
      - expires_in
      title: WebTokenResponse
    Body_admin_fill_batch_admin_forms__form_id__fill_batch_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
        mapping:
          type: string
          title: Mapping
      type: object
      required:
      - file
      - mapping
      title: Body_admin_fill_batch_admin_forms__form_id__fill_batch_post
    WebTokenLimitsResponse:
      properties:
        api_base:
          type: string
          title: Api Base
        limits:
          $ref: '#/components/schemas/UploadLimits'
      type: object
      required:
      - api_base
      - limits
      title: WebTokenLimitsResponse
    BillingBreakdownResponse:
      properties:
        month:
          type: string
          title: Month
        rows:
          items:
            $ref: '#/components/schemas/BreakdownRow'
          type: array
          title: Rows
        total_cents:
          type: integer
          title: Total Cents
      type: object
      required:
      - month
      - rows
      - total_cents
      title: BillingBreakdownResponse
    InvoiceRow:
      properties:
        period:
          type: string
          title: Period
        amount_cents:
          type: integer
          title: Amount Cents
        status:
          type: string
          title: Status
        hosted_invoice_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Hosted Invoice Url
        invoice_pdf:
          anyOf:
          - type: string
          - type: 'null'
          title: Invoice Pdf
      type: object
      required:
      - period
      - amount_cents
      - status
      title: InvoiceRow
    Body_admin_create_with_context_admin_forms_with_context_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
        context:
          items:
            type: string
            contentMediaType: application/octet-stream
          type: array
          title: Context
          default: []
      type: object
      required:
      - file
      title: Body_admin_create_with_context_admin_forms_with_context_post
    Body_admin_suggest_mapping_admin_forms__form_id__suggest_mapping_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
      type: object
      required:
      - file
      title: Body_admin_suggest_mapping_admin_forms__form_id__suggest_mapping_post
    FormStatus:
      properties:
        id:
          type: string
          title: Id
        status:
          type: string
          title: Status
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        schema_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Schema Version
        warnings:
          items:
            type: string
          type: array
          title: Warnings
          default: []
        reused_layout:
          type: boolean
          title: Reused Layout
          default: false
        library:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Library
        retention:
          anyOf:
          - $ref: '#/components/schemas/Retention'
          - type: 'null'
        artifact_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Artifact Id
        source_artifact_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Artifact Id
      type: object
      required:
      - id
      - status
      title: FormStatus
    FormSummary:
      properties:
        id:
          type: string
          title: Id
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        status:
          type: string
          title: Status
        created_at:
          type: string
          title: Created At
        has_thumbnail:
          type: boolean
          title: Has Thumbnail
          default: false
        no_fields:
          type: boolean
          title: No Fields
          default: false
        retention:
          anyOf:
          - $ref: '#/components/schemas/Retention'
          - type: 'null'
      type: object
      required:
      - id
      - status
      - created_at
      title: FormSummary
    FormCreated:
      properties:
        form_id:
          type: string
          title: Form Id
        status:
          type: string
          title: Status
        library:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Library
        source_artifact_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Artifact Id
      type: object
      required:
      - form_id
      - status
      title: FormCreated
    UploadLimits:
      properties:
        max_upload_bytes:
          type: integer
          title: Max Upload Bytes
        max_request_bytes:
          type: integer
          title: Max Request Bytes
        max_context_files:
          type: integer
          title: Max Context Files
      type: object
      required:
      - max_upload_bytes
      - max_request_bytes
      - max_context_files
      title: UploadLimits
    UsageDayRow:
      properties:
        date:
          type: string
          title: Date
        create:
          type: integer
          title: Create
          default: 0
        with_context:
          type: integer
          title: With Context
          default: 0
        standard_fill:
          type: integer
          title: Standard Fill
          default: 0
        verify:
          type: integer
          title: Verify
          default: 0
      type: object
      required:
      - date
      title: UsageDayRow
    ActivityResponse:
      properties:
        events:
          items:
            $ref: '#/components/schemas/ActivityEvent'
          type: array
          title: Events
        total_count:
          type: integer
          title: Total Count
        page:
          type: integer
          title: Page
        page_size:
          type: integer
          title: Page Size
      type: object
      required:
      - events
      - total_count
      - page
      - page_size
      title: ActivityResponse
    ConsentBody:
      properties:
        req:
          type: string
          title: Req
        user_id:
          type: string
          title: User Id
        decision:
          type: string
          title: Decision
      type: object
      required:
      - req
      - user_id
      - decision
      title: ConsentBody
    Body_admin_fill_existing_admin_forms__form_id__with_context_post:
      properties:
        context:
          items:
            type: string
            contentMediaType: application/octet-stream
          type: array
          title: Context
          default: []
      type: object
      title: Body_admin_fill_existing_admin_forms__form_id__with_context_post
    BatchCreated:
      properties:
        batch_id:
          type: string
          title: Batch Id
      type: object
      required:
      - batch_id
      title: BatchCreated
    BreakdownRow:
      properties:
        kind:
          type: string
          title: Kind
        label:
          type: string
          title: Label
        ops:
          type: integer
          title: Ops
        free_applied:
          type: integer
          title: Free Applied
        included_pages:
          anyOf:
          - type: integer
          - type: 'null'
          title: Included Pages
        additional_pages:
          anyOf:
          - type: integer
          - type: 'null'
          title: Additional Pages
        base_cents:
          type: integer
          title: Base Cents
        additional_cents:
          type: integer
          title: Additional Cents
        total_cents:
          type: integer
          title: Total Cents
      type: object
      required:
      - kind
      - label
      - ops
      - free_applied
      - included_pages
      - additional_pages
      - base_cents
      - additional_cents
      - total_cents
      title: BreakdownRow
    UsageKeyRow:
      properties:
        key_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Id
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        last4:
          anyOf:
          - type: string
          - type: 'null'
          title: Last4
        counts:
          $ref: '#/components/schemas/UsageCounts'
        total:
          type: integer
          title: Total
      type: object
      required:
      - key_id
      - label
      - last4
      - counts
      - total
      title: UsageKeyRow
    SetupIntentResponse:
      properties:
        client_secret:
          type: string
          title: Client Secret
      type: object
      required:
      - client_secret
      title: SetupIntentResponse
    UsageTrendResponse:
      properties:
        by_day:
          items:
            $ref: '#/components/schemas/UsageDayRow'
          type: array
          title: By Day
      type: object
      required:
      - by_day
      title: UsageTrendResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BatchRun:
      properties:
        id:
          type: string
          title: Id
        form_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Form Id
        form_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Form Name
        status:
          type: string
          title: Status
        total:
          type: integer
          title: Total
        filled:
          type: integer
          title: Filled
        failed:
          type: integer
          title: Failed
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        created_at:
          type: string
          title: Created At
      type: object
      required:
      - id
      - status
      - total
      - filled
      - failed
      - created_at
      title: BatchRun
    UsageCounts:
      properties:
        create:
          type: integer
          title: Create
          default: 0
        with_context:
          type: integer
          title: With Context
          default: 0
        standard_fill:
          type: integer
          title: Standard Fill
          default: 0
        verify:
          type: integer
          title: Verify
          default: 0
        read:
          type: integer
          title: Read
          default: 0
        package:
          type: integer
          title: Package
          default: 0
        send_fax:
          type: integer
          title: Send Fax
          default: 0
        utility:
          type: integer
          title: Utility
          default: 0
      type: object
      title: UsageCounts
      description: Per-kind counts. One field per kind in billing_math.USAGE_KINDS.
    BatchRunsResponse:
      properties:
        runs:
          items:
            $ref: '#/components/schemas/BatchRun'
          type: array
          title: Runs
        total_count:
          type: integer
          title: Total Count
        page_size:
          type: integer
          title: Page Size
      type: object
      required:
      - runs
      - total_count
      - page_size
      title: BatchRunsResponse
    ActivityEvent:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          title: Created At
        kind:
          type: string
          title: Kind
        key_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Id
        key_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Label
        pages:
          anyOf:
          - type: integer
          - type: 'null'
          title: Pages
        context_pages:
          anyOf:
          - type: integer
          - type: 'null'
          title: Context Pages
        form_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Form Id
      type: object
      required:
      - id
      - created_at
      - kind
      - key_id
      - key_label
      - pages
      - context_pages
      - form_id
      title: ActivityEvent
    BatchFormCount:
      properties:
        runs:
          type: integer
          title: Runs
        last_status:
          type: string
          title: Last Status
        last_at:
          type: string
          title: Last At
      type: object
      required:
      - runs
      - last_status
      - last_at
      title: BatchFormCount
    PaymentMethodResponse:
      properties:
        has_payment_method:
          type: boolean
          title: Has Payment Method
        brand:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand
        last4:
          anyOf:
          - type: string
          - type: 'null'
          title: Last4
      type: object
      required:
      - has_payment_method
      title: PaymentMethodResponse
    MappingSuggestion:
      properties:
        mapping:
          additionalProperties: true
          type: object
          title: Mapping
        unmapped_columns:
          items:
            type: string
          type: array
          title: Unmapped Columns
          default: []
      type: object
      required:
      - mapping
      title: MappingSuggestion
    Body_admin_create_form_admin_forms_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
      type: object
      required:
      - file
      title: Body_admin_create_form_admin_forms_post
    FormsListResponse:
      properties:
        forms:
          items:
            $ref: '#/components/schemas/FormSummary'
          type: array
          title: Forms
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
      type: object
      required:
      - forms
      - total
      - limit
      - offset
      title: FormsListResponse
    BatchCountsResponse:
      properties:
        counts:
          additionalProperties:
            $ref: '#/components/schemas/BatchFormCount'
          type: object
          title: Counts
      type: object
      required:
      - counts
      title: BatchCountsResponse
    BatchStatus:
      properties:
        status:
          type: string
          title: Status
        total:
          type: integer
          title: Total
        filled:
          type: integer
          title: Filled
        failed:
          type: integer
          title: Failed
        results:
          items: {}
          type: array
          title: Results
          default: []
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        retention:
          anyOf:
          - $ref: '#/components/schemas/Retention'
          - type: 'null'
      type: object
      required:
      - status
      - total
      - filled
      - failed
      title: BatchStatus
    Body_admin_library_store_admin_library__slug__store_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
        sha256:
          type: string
          title: Sha256
        revision:
          type: string
          title: Revision
          default: ''
        page_count:
          type: integer
          title: Page Count
          default: 0
        make_fillable:
          type: string
          title: Make Fillable
          default: 'true'
      type: object
      required:
      - file
      - sha256
      title: Body_admin_library_store_admin_library__slug__store_post
    ContextJobStatus:
      properties:
        job_id:
          type: string
          title: Job Id
        status:
          type: string
          title: Status
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        proposal_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Proposal Id
        result:
          anyOf:
          - type: string
          - type: 'null'
          title: Result
        receipt_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Receipt Url
        pdf_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Pdf Url
        package_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Package Url
        report:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Report
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorDetail'
          - type: 'null'
        retention:
          anyOf:
          - $ref: '#/components/schemas/Retention'
          - type: 'null'
        artifact_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Artifact Id
        artifacts:
          items: {}
          type: array
          title: Artifacts
          default: []
      type: object
      required:
      - job_id
      - status
      title: ContextJobStatus
    UsageResponse:
      properties:
        owner:
          type: string
          title: Owner
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        period:
          type: string
          title: Period
        total:
          $ref: '#/components/schemas/UsageCounts'
        period_counts:
          $ref: '#/components/schemas/UsageCounts'
        total_pages:
          $ref: '#/components/schemas/UsageCounts'
          default:
            create: 0
            with_context: 0
            standard_fill: 0
            verify: 0
            read: 0
            package: 0
            send_fax: 0
            utility: 0
        period_pages:
          $ref: '#/components/schemas/UsageCounts'
          default:
            create: 0
            with_context: 0
            standard_fill: 0
            verify: 0
            read: 0
            package: 0
            send_fax: 0
            utility: 0
        total_ctx_tokens:
          $ref: '#/components/schemas/UsageCounts'
          default:
            create: 0
            with_context: 0
            standard_fill: 0
            verify: 0
            read: 0
            package: 0
            send_fax: 0
            utility: 0
        period_ctx_tokens:
          $ref: '#/components/schemas/UsageCounts'
          default:
            create: 0
            with_context: 0
            standard_fill: 0
            verify: 0
            read: 0
            package: 0
            send_fax: 0
            utility: 0
        total_context_pages:
          $ref: '#/components/schemas/UsageCounts'
          default:
            create: 0
            with_context: 0
            standard_fill: 0
            verify: 0
            read: 0
            package: 0
            send_fax: 0
            utility: 0
        period_context_pages:
          $ref: '#/components/schemas/UsageCounts'
          default:
            create: 0
            with_context: 0
            standard_fill: 0
            verify: 0
            read: 0
            package: 0
            send_fax: 0
            utility: 0
      type: object
      required:
      - owner
      - period
      - total
      - period_counts
      title: UsageResponse
    Retention:
      properties:
        policy:
          type: string
          title: Policy
        documents_deleted_after:
          anyOf:
          - type: string
          - type: 'null'
          title: Documents Deleted After
        documents_deleted_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Documents Deleted At
      type: object
      required:
      - policy
      title: Retention
    ErrorDetail:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
      type: object
      required:
      - code
      - message
      title: ErrorDetail
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ContextJobCreated:
      properties:
        job_id:
          type: string
          title: Job Id
        status:
          type: string
          title: Status
          default: processing
      type: object
      required:
      - job_id
      title: ContextJobCreated
    UsageDetailResponse:
      properties:
        month:
          type: string
          title: Month
        by_day:
          items:
            $ref: '#/components/schemas/UsageDayRow'
          type: array
          title: By Day
        by_kind:
          $ref: '#/components/schemas/UsageCounts'
        by_key:
          items:
            $ref: '#/components/schemas/UsageKeyRow'
          type: array
          title: By Key
        month_total:
          type: integer
          title: Month Total
      type: object
      required:
      - month
      - by_day
      - by_kind
      - by_key
      - month_total
      title: UsageDetailResponse
    InvoicesResponse:
      properties:
        invoices:
          items:
            $ref: '#/components/schemas/InvoiceRow'
          type: array
          title: Invoices
      type: object
      required:
      - invoices
      title: InvoicesResponse
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: Emboss API key (sk_...)
      description: An Emboss API key. See https://getemboss.ai/docs/authentication.
    oauth2:
      type: oauth2
      description: Sign in with your Emboss account. See https://getemboss.ai/docs/authentication.
      flows:
        authorizationCode:
          authorizationUrl: https://api.getemboss.ai/oauth/authorize
          tokenUrl: https://api.getemboss.ai/oauth/token
          scopes:
            forms:read: Read your forms
            forms:write: Create and fill forms