FilingSift Contract API

openapi: 3.2.0
info:
  title: FilingSift Contract 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: Contract
  description: API lifecycle and schema metadata
paths:
  /meta:
    get:
      tags:
      - Contract
      operationId: getApiMetadata
      summary: Get the current API and schema versions
      responses:
        '200':
          description: Current contract metadata and capability gates
          headers:
            X-API-Version:
              $ref: '#/components/headers/ApiVersion'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataResponse'
        '304':
          $ref: '#/components/responses/NotModified'
        '429':
          $ref: '#/components/responses/RateLimited'
  /deprecation-policy:
    get:
      tags:
      - Contract
      operationId: getDeprecationPolicy
      summary: Get the v1 compatibility and retirement policy
      responses:
        '200':
          description: Active version policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeprecationPolicyResponse'
        '304':
          $ref: '#/components/responses/NotModified'
        '429':
          $ref: '#/components/responses/RateLimited'
  /status:
    get:
      tags:
      - Contract
      operationId: getPublicStatus
      summary: Read public service and ingestion status
      responses:
        '200':
          description: Public component status
  /changelog:
    get:
      tags:
      - Contract
      operationId: getPublicChangelog
      summary: Read dated public product changes
      responses:
        '200':
          description: Public changelog
  /status/history:
    get:
      tags:
      - Contract
      operationId: getPublicStatusHistory
      summary: Read observed API availability and latency plus current ingestion delay
      parameters:
      - name: days
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 90
          default: 30
      responses:
        '200':
          description: Customer-data-free operational history; observed measurements are not an SLA
  /incidents:
    get:
      tags:
      - Contract
      operationId: getPublicIncidents
      summary: Read the public incident ledger
      responses:
        '200':
          description: Public incident ledger
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
    MetadataResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: object
          required:
          - apiVersion
          - schemaVersion
          - stability
          - deprecationPolicy
          - minimumDeprecationNoticeDays
          - monitoringEmail
          - financingAlertsAndScreensV2
          - savedFinancingScreens
          - savedScreenAlerts
          - customerExportDestinations
          - warehouseExportDestinations
          - filingReader
          - searchAndScreening
          - savedSearchAlerts
          - dataRights
          - webhooks
          - citedAi
          - mcp
          - customerAutomation
          - enterpriseControls
          - authentication
          properties:
            apiVersion:
              type: string
              const: '1'
            schemaVersion:
              type: string
              const: 1.0.0
            stability:
              type: string
              const: stable
            deprecationPolicy:
              type: string
            minimumDeprecationNoticeDays:
              type: integer
              const: 180
            monitoringEmail:
              type: string
              const: available_license_free
            financingAlertsAndScreensV2:
              type: string
              const: screening_available_alert_delivery_acceptance_pending
            savedFinancingScreens:
              type: string
              const: available_license_free
            savedScreenAlerts:
              type: string
              const: acceptance_pending_customer_disabled
            customerExportDestinations:
              type: array
              const:
              - s3
              - google_sheets
            warehouseExportDestinations:
              type: string
              const: acceptance_pending_customer_disabled
            filingReader:
              type: string
              const: available_license_free
            searchAndScreening:
              type: string
              const: available_license_free
            savedSearchAlerts:
              type: string
              const: available_license_free
            dataRights:
              type: object
              required:
              - policyVersion
              - status
              - legalEffect
              - licenseFreeInputs
              - excludedFromLicenseFreePlan
              - issuerMaterial
              - admissionRule
              properties:
                policyVersion:
                  type: string
                  const: '2026-10-09'
                status:
                  type: string
                  const: product_boundary_pending_legal_review
                legalEffect:
                  type: string
                  const: not_legal_advice_or_a_redistribution_license
                licenseFreeInputs:
                  type: array
                  items:
                    type: string
                excludedFromLicenseFreePlan:
                  type: array
                  minItems: 9
                  maxItems: 9
                  items:
                    type: string
                    enum:
                    - broker_research
                    - expert_call_libraries
                    - consensus_estimates
                    - commercial_news_archives
                    - earnings_call_audio_and_third_party_transcripts
                    - proprietary_market_data
                    - private_company_financials
                    - commercial_aggregator_global_filings
                    - issuer_presentation_redistribution
                issuerMaterial:
                  type: object
                  required:
                  - publicSourceLinking
                  - contentRedistribution
                  - defaultHandling
                  properties:
                    publicSourceLinking:
                      type: string
                      const: allowed
                    contentRedistribution:
                      type: string
                      const: requires_documented_rights_and_commercial_review
                    defaultHandling:
                      type: string
                      const: link_only
                admissionRule:
                  type: string
                  const: written_rights_and_commercial_review_required_before_ingestion_or_customer_redistribution
            webhooks:
              type: string
              description: First failing production gate for customer product webhooks.
            citedAi:
              type: string
              description: First failing production gate for generated cited research.
            mcp:
              type: string
              description: First failing production gate for MCP.
            customerAutomation:
              type: object
              description: Shared benchmark evidence plus each feature's required release checks; the read-only REST-backed MCP transport does not require the generated-interpretation benchmark. No secret values are returned.
              additionalProperties: true
            enterpriseControls:
              type: object
              description: Public demand-gated enterprise procurement state. Controlled pilots remain available; unfinished controls and assurance claims remain false.
              additionalProperties: true
            authentication:
              type: string
              const: email_password_sessions_and_api_keys_available
        meta:
          $ref: '#/components/schemas/ApiMeta'
    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'
    DeprecationPolicyResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: object
          required:
          - currentVersion
          - currentSchemaVersion
          - status
          - breakingChanges
          - notice
          - lifecycleHeaders
          - currentSunsetDate
          properties:
            currentVersion:
              type: string
              const: '1'
            currentSchemaVersion:
              type: string
              const: 1.0.0
            status:
              type: string
              const: active
            breakingChanges:
              type: string
            notice:
              type: string
            lifecycleHeaders:
              type: array
              items:
                type: string
            currentSunsetDate:
              type: 'null'
        meta:
          $ref: '#/components/schemas/ApiMeta'
    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:
    RateLimited:
      description: API-wide fixed-window request limit exceeded
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotModified:
      description: Representation matches If-None-Match; response has no body
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
        X-API-Version:
          $ref: '#/components/headers/ApiVersion'
  headers:
    RateLimitReset:
      description: Seconds until the current fixed window resets
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests remaining in the current window
      schema:
        type: integer
    ApiVersion:
      description: Major API version
      schema:
        type: string
        const: '1'
    RetryAfter:
      description: Seconds before retrying
      schema:
        type: integer
    RateLimitLimit:
      description: Request limit for the current fixed window
      schema:
        type: integer
    ETag:
      description: Strong SHA-256 entity tag for conditional GETs
      schema:
        type: string
  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.