FilingSift Developer API

openapi: 3.2.0
info:
  title: FilingSift Developer API
  version: 1.0.0
  description: FilingSift v1 REST contract for source-cited SEC filing facts, facilities, covenants, filing comparisons, research workflows, and reference-source intelligence. Responses preserve source evidence, provenance, uncertainty, and validation status so every result can be traced to its origin. Route availability follows the production service and the authenticated account's permissions; current endpoint responses are authoritative. FilingSift does not automatically assign materiality, investment, financial, or legal conclusions. Request limits, authentication, issuer/history access, and pagination differ by resource. The URL query guard does not count JSON body fields. Query cost equals 5 plus the effective query-string limit (20 when omitted), plus 3 for each query parameter other than limit and cursor, plus 2 when a cursor is present. X-Query-Cost and X-Max-Query-Cost report the applied and allowed amounts when the request reaches the query guard; earlier refusals may omit them. Plan limits stop requests or account actions; they do not create overage charges. The SEC worker restarts one minute after its prior bounded run completes, plus randomized delay, with an operating target of discovery within five minutes of SEC acceptance. Extraction and delivery follow asynchronously. Active reference sources fetch on the first eligible cache miss with source-specific caches from five minutes to six hours. Treasury, Federal Reserve Board, OFR, BIS, the FDIC and GLEIF expansion datasets, and the Treasury Fiscal combined report have no deployed saved monitor. Alert mode instant makes a processed alert due for the next ingestion monitoring stage; quiet hours, capacity, and retries can defer delivery. Operating targets are not current-state claims; GET /coverage/status is authoritative for current SEC backlog and delay.
  contact:
    name: FilingSift Support
    email: support@filingsift.com
servers:
- url: https://api.filingsift.com/api/v1
  description: FilingSift production API
- url: http://127.0.0.1:5000/api/v1
  description: Local development
tags:
- name: Developer
  description: Filing streams
  parsed representations: null
  scoped credentials: null
  archives: null
  telemetry: null
  and gated webhooks: null
paths:
  /developer/sandbox:
    get:
      tags:
      - Developer
      operationId: getDeveloperSandbox
      summary: Read clearly labeled illustrative filing, stream, and archive examples
      security: []
      responses:
        '200':
          description: Illustrative sandbox data that cannot be mistaken for an SEC filing
  /filings/stream:
    get:
      tags:
      - Developer
      operationId: streamFilings
      summary: Stream newly indexed entitled filings with reconnectable SSE cursors
      description: Deployed migration 028 route. Requires explicit stream:read, current billing access, and the organization's selected issuers/history window. Persist eventId for reconnects through cursor or Last-Event-ID; cursor takes precedence. follow=false emits at most 100 available events and closes. Following streams send 15-second heartbeat comments. Consumers are responsible for reconnection and deduplication.
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      parameters:
      - name: cursor
        in: query
        schema:
          type: string
      - name: cik
        in: query
        schema:
          type: string
      - name: ticker
        in: query
        schema:
          type: string
      - name: form
        in: query
        schema:
          type: string
      - name: follow
        in: query
        schema:
          type: boolean
          default: true
      - name: Last-Event-ID
        in: header
        schema:
          type: string
      responses:
        '200':
          description: Filing event stream
          content:
            text/event-stream:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /filings/{accession}/parsed.html:
    get:
      tags:
      - Developer
      operationId: getParsedFilingHtml
      summary: Render safe HTML from parsed sections and tables without serving raw SEC HTML
      description: Deployed route requiring filings:read, billing access, and plan history. The current router does not apply the stream's selected-company filter. The configured response byte limit applies; this is rendered parsed output, not the original SEC document.
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      parameters:
      - name: accession
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Parsed HTML
          content:
            text/html:
              schema:
                type: string
  /filings/{accession}/parsed.txt:
    get:
      tags:
      - Developer
      operationId: getParsedFilingText
      summary: Render parsed filing and exhibit text with SEC source headers
      description: Deployed route requiring filings:read, billing access, and plan history. No selected-company filter is applied by the current router. Text is limited to stored parsed sections and selected indexed exhibits and is subject to the configured response byte limit.
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      parameters:
      - name: accession
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Parsed text
          content:
            text/plain:
              schema:
                type: string
  /filings/{accession}/tables.json:
    get:
      tags:
      - Developer
      operationId: getParsedFilingTables
      summary: Read source-linked parsed filing and exhibit tables
      description: Deployed route requiring filings:read, billing access, and plan history. No selected-company filter is applied by the current router. Returns stored parsed tables rather than every table or attachment in the SEC filing; the JSON response size limit applies.
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      parameters:
      - name: accession
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Parsed table JSON
  /filings/{accession}/xbrl.json:
    get:
      tags:
      - Developer
      operationId: getFilingXbrlJson
      summary: Read raw XBRL facts, contexts, networks, mappings, and explicit conflicts
      description: Deployed route requiring filings:read, billing access, and plan history; no selected-company filter is applied by the current router. Reads at most 5000 facts and 500 conflicts without continuation. Use /xbrl/facts for paginated raw observations. Contexts are parsed representations retaining source context IDs, not original scenario XML.
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      parameters:
      - name: accession
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Source-linked XBRL JSON
        '404':
          $ref: '#/components/responses/NotFound'
  /filings/{accession}/clean.pdf:
    get:
      tags:
      - Developer
      operationId: getCleanFilingPdf
      summary: Download a bounded clean evidence PDF with clickable SEC sources
      description: Deployed route requiring filings:read, billing access, and plan history; no selected-company filter is applied by the current router. This is a source-linked evidence report, not a facsimile or complete reproduction of the SEC document. The configured response byte limit applies.
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      parameters:
      - name: accession
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Clean evidence PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
  /account/developer:
    get:
      tags:
      - Developer
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      operationId: getDeveloperOverview
      summary: Read developer resources, caps, and benchmark gates
      responses:
        '200':
          description: Developer-platform overview
  /account/service-accounts:
    post:
      tags:
      - Developer
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      operationId: createServiceAccount
      summary: Create an expiring least-privilege service credential
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - scopes
              properties:
                name:
                  type: string
                  maxLength: 120
                scopes:
                  type: array
                  minItems: 1
                  maxItems: 16
                  items:
                    type: string
                expiresInDays:
                  type: integer
                  minimum: 1
                  maximum: 365
                  default: 90
                rotateAfterDays:
                  type: integer
                  minimum: 1
                  maximum: 365
                  default: 60
      responses:
        '201':
          description: Service account and one-time credential
  /account/service-accounts/{service_account_id}:
    delete:
      tags:
      - Developer
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      operationId: disableServiceAccount
      summary: Disable the service account and revoke its keys atomically
      parameters:
      - name: service_account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Disabled service account
  /account/api-keys/{key_id}/telemetry:
    get:
      tags:
      - Developer
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      operationId: getApiKeyTelemetry
      summary: Read bounded daily usage, latency, bytes, and errors
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: days
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 90
          default: 30
      responses:
        '200':
          description: Per-key daily telemetry
  /account/batch-jobs:
    get:
      tags:
      - Developer
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      operationId: listBatchJobs
      summary: List the organization batch queue
      responses:
        '200':
          description: Batch jobs
    post:
      tags:
      - Developer
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      operationId: createBatchJob
      summary: Queue a bounded filing, exhibit, fact, or event archive
      description: Requires a credential and batch:write. Accepts 1–100 accessions; processing checks current billing plus the issuer/history grant captured at submission, and missing accessions fail the job. Expanded archive kinds are deployed migration 028 functionality. expiresAt is set to seven days after creation; both stores enforce it at read time independently of retention cleanup. Result payloads are capped at 25 MB and fact archives at 25000 output records. Fact selection exhausts 500-row XBRL cursor pages, checks retained package count/identity before completion, and falls back to deterministic source-bound filing facts only for absent/not-available legacy packages. Overflow or source change refuses the whole archive. This is a complete retained-fact export within the bounds, not every original SEC XBRL construct, a complete filing package, or a market archive.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - kind
              - items
              properties:
                kind:
                  type: string
                  enum:
                  - filing_bundle
                  - filing_archive
                  - exhibit_archive
                  - fact_archive
                  - event_archive
                items:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
      responses:
        '202':
          description: Batch job queued
  /account/batch-jobs/{job_id}:
    get:
      tags:
      - Developer
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      operationId: getBatchJob
      summary: Read batch queue, completion, failure, and manifest state
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Batch job status
  /account/batch-jobs/{job_id}/download:
    get:
      tags:
      - Developer
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      operationId: downloadBatchJob
      summary: Download a completed source-retaining archive and checksum manifest
      description: Requires a credential with batch:read, a job owned by the current organization, succeeded status, current billing, an unexpired seven-day timestamp, and every retained source within both the original and current issuer/history grants. Legacy jobs without an access receipt fail closed. Payload and manifest integrity are revalidated before download; non-succeeded jobs return 409. X-Manifest-Sha256 hashes the canonical manifest excluding its hash fields; X-Export-Sha256 hashes the canonical result, not the downloaded JSON bytes containing the manifest. This attachment uses no-store and bypasses the JSON middleware response cap; the generation payload cap is separate.
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: JSON archive with checksum manifest
        '409':
          $ref: '#/components/responses/Conflict'
  /account/webhooks:
    get:
      tags:
      - Developer
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      operationId: listProductWebhooks
      summary: Read endpoints and the qualified-benchmark activation gate
      responses:
        '200':
          description: Product webhook configuration
    post:
      tags:
      - Developer
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      operationId: createProductWebhook
      summary: Create a signed endpoint only after the benchmark gate opens
      responses:
        '201':
          description: Endpoint and one-time signing secret
  /account/webhook-deliveries:
    get:
      tags:
      - Developer
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      operationId: listProductWebhookDeliveries
      summary: Read delivery, retry, and dead-letter state
      responses:
        '200':
          description: Product webhook delivery log
  /account/webhook-deliveries/{delivery_id}/replay:
    post:
      tags:
      - Developer
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      operationId: replayProductWebhookDelivery
      summary: Replay a dead-letter delivery only after the benchmark gate opens
      parameters:
      - name: delivery_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Delivery requeued
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - reason
          properties:
            code:
              type: string
            message:
              type: string
            reason:
              $ref: '#/components/schemas/ErrorReason'
        requestId:
          type: string
        meta:
          $ref: '#/components/schemas/ApiMeta'
    ErrorReason:
      type: object
      required:
      - category
      - retryable
      properties:
        category:
          type: string
          enum:
          - request
          - rate_limit
          - response_limit
          - service
        retryable:
          type: boolean
        retryAfterSeconds:
          type: integer
        details:
          type:
          - object
          - 'null'
          additionalProperties: true
        maximumCost:
          type: integer
        calculatedCost:
          type: integer
        maximumBytes:
          type: integer
        actualBytes:
          type: integer
    ApiMeta:
      type: object
      required:
      - schemaVersion
      - apiVersion
      properties:
        schemaVersion:
          type: string
          const: 1.0.0
        apiVersion:
          type: string
          const: '1'
        mode:
          type: string
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      type: object
      required:
      - limit
      - returned
      - hasMore
      - nextCursor
      properties:
        limit:
          type: integer
          minimum: 1
          maximum: 100
        returned:
          type: integer
          minimum: 0
          maximum: 100
        hasMore:
          type: boolean
        nextCursor:
          type:
          - string
          - 'null'
  responses:
    Forbidden:
      description: Valid key lacks a required scope, role, entitlement, history window, or platform-admin status
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing, malformed, expired, revoked, or invalid account session/API key, or incorrect login credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: Requested account transition violates a current-state constraint
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BrowserSession:
      type: apiKey
      in: cookie
      name: __Host-filingsift_session
      description: Secure HttpOnly SameSite=Lax production browser cookie, set by authentication responses. Raw tokens are not returned to browser JavaScript. Cookie-authenticated mutations require a trusted Origin and X-FilingSift-CSRF header equal to 1. API keys do not authenticate browser-only workspace operations.
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: FilingSift API key
      description: High-entropy fs_live API key in Authorization. FilingSift persists only token hashes. Production browser sessions use BrowserSession cookies, not Bearer tokens.