FilingSift XBRL API

openapi: 3.2.0
info:
  title: FilingSift XBRL 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: XBRL
  description: Deployed public raw-fact and network resources. The current router does not apply issuer or plan-history filters; composite responses are bounded.
paths:
  /xbrl/mappings:
    get:
      tags:
      - XBRL
      operationId: getXbrlMappings
      summary: Get the versioned transparent standard-concept mapping registry
      description: Public exact-concept mappings for 11 standard concepts; issuer extensions can remain unmapped. This is not a complete normalized taxonomy.
      responses:
        '200':
          description: Mapping registry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
  /xbrl/facts:
    get:
      tags:
      - XBRL
      operationId: listXbrlFacts
      summary: List raw XBRL facts with source context IDs, parsed contexts, and units
      description: Public fact-ID pagination in meta.pagination. Reuse nextCursor as cursor; it is not a filter-bound snapshot cursor. Contexts retain parsed entity, period, dimensions, and a scenario-present flag, not arbitrary scenario XML. Shared query-cost and response-size limits also apply, so the route maximum of 500 may exceed the configured request budget.
      parameters:
      - in: query
        name: cik
        schema:
          type: string
          pattern: ^[0-9]{1,10}$
      - in: query
        name: accession
        schema:
          type: string
      - in: query
        name: concept
        schema:
          type: string
      - in: query
        name: standard_concept
        schema:
          type: string
      - in: query
        name: period_end
        schema:
          type: string
          format: date
      - in: query
        name: dimension_kind
        schema:
          type: string
          enum:
          - segment
          - geography
          - product
          - legal_entity
          - other
      - in: query
        name: cursor
        schema:
          type: string
          pattern: ^[0-9a-f]{64}$
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
      responses:
        '200':
          description: Raw XBRL facts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
  /xbrl/statements:
    get:
      tags:
      - XBRL
      operationId: getXbrlStatements
      summary: Get as-reported financial statement networks and their raw facts
      description: Public bounded view of one package; reads at most 5000 facts and 500 conflicts without continuation. Use paged raw facts for larger packages.
      parameters:
      - in: query
        name: accession
        required: true
        schema:
          type: string
      - in: query
        name: statement
        schema:
          type: string
          enum:
          - income_statement
          - balance_sheet
          - cash_flow_statement
      responses:
        '200':
          description: As-reported statements
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /xbrl/disclosures:
    get:
      tags:
      - XBRL
      operationId: getXbrlDisclosures
      summary: Get disclosure-topic and roll-forward-candidate networks
      description: Public view reading at most 5000 facts without continuation. Network roles and roll-forward flags do not establish complete footnote extraction.
      parameters:
      - in: query
        name: accession
        required: true
        schema:
          type: string
      - in: query
        name: topic
        schema:
          type: string
      responses:
        '200':
          description: As-reported disclosure networks
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /xbrl/quarters:
    get:
      tags:
      - XBRL
      operationId: getXbrlQuarters
      summary: Get reported quarters and compatible source-linked YTD disaggregation
      description: Reads at most 5000 facts. Reported-quarter candidates use 70–110-day durations; YTD subtraction uses compatible observations up to 300 days. Annual-minus-nine-month Q4 derivation is outside this endpoint.
      parameters:
      - in: query
        name: cik
        required: true
        schema:
          type: string
      - in: query
        name: standard_concept
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Reported and derived quarters
        '400':
          $ref: '#/components/responses/BadRequest'
  /xbrl/revisions:
    get:
      tags:
      - XBRL
      operationId: getXbrlRevisions
      summary: Get cross-filing fact revision history
      description: Public view of differing comparable observations from at most 5000 facts. It does not identify formal restatements or retain every parser revision.
      parameters:
      - in: query
        name: cik
        required: true
        schema:
          type: string
      - in: query
        name: standard_concept
        schema:
          type: string
      responses:
        '200':
          description: Revision history
        '400':
          $ref: '#/components/responses/BadRequest'
  /xbrl/timeseries:
    get:
      tags:
      - XBRL
      operationId: getXbrlTimeSeries
      summary: Get chart-ready source-linked standard-concept history
      description: Public bounded view reading at most 5000 facts without continuation; not a complete historical archive.
      parameters:
      - in: query
        name: cik
        required: true
        schema:
          type: string
      - in: query
        name: standard_concept
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Time-series data
        '400':
          $ref: '#/components/responses/BadRequest'
  /xbrl/peers:
    get:
      tags:
      - XBRL
      operationId: getXbrlPeerTable
      summary: Get a bounded cross-company period table
      description: Accepts 2–25 distinct comma-separated CIKs and reads at most 500 matching facts per issuer. Missing values and conflicts remain explicit.
      parameters:
      - in: query
        name: ciks
        required: true
        schema:
          type: string
      - in: query
        name: standard_concept
        required: true
        schema:
          type: string
      - in: query
        name: period_end
        required: true
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Peer table
        '400':
          $ref: '#/components/responses/BadRequest'
  /xbrl/conflicts:
    get:
      tags:
      - XBRL
      operationId: listXbrlConflicts
      summary: List unresolved values sharing concept, period, dimensions, and unit
      description: Public bounded result of at most 500 conflicts with no continuation cursor; the server does not select a winning value.
      parameters:
      - in: query
        name: cik
        schema:
          type: string
      - in: query
        name: accession
        schema:
          type: string
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
      responses:
        '200':
          description: Explicit XBRL conflicts
        '400':
          $ref: '#/components/responses/BadRequest'
  /xbrl/comparability:
    get:
      tags:
      - XBRL
      operationId: reviewXbrlComparability
      summary: Review bounded financial fact alternatives without selecting a winner
      description: Deployed with representative public-data and automated competing-context, unit, period, source-availability and pair-bound acceptance. Requires CIK and a registry standard concept; optional period_end narrows the candidate set. Reads limit plus one facts to detect truncation, then compares at most limit facts. No continuation cursor; narrow the request or use paged raw facts. A nontruncated read does not establish complete SEC coverage. Context, unit, scope, mapping and numeric alternatives remain explicit. No winning value, analyst override, formal restatement or verification upgrade is produced. All bounded pairs are evaluated; at most 200 prioritized pair details are returned with separate comparisonsTruncated and inputTruncated flags. Summary counts include all evaluated pairs. Shared response-size limits apply. A missing XBRL fact source returns HTTP 503, not an empty successful review.
      security: []
      parameters:
      - in: query
        name: cik
        required: true
        schema:
          type: string
          pattern: ^[0-9]{1,10}$
      - in: query
        name: standard_concept
        required: true
        description: A standardConcept from /xbrl/mappings
        schema:
          type: string
      - in: query
        name: period_end
        schema:
          type: string
          format: date
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 40
      responses:
        '200':
          description: Bounded no-winner comparability review with explicit input truncation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialComparabilityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: XBRL fact source unavailable; error code xbrl_review_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
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'
    GenericResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: object
          additionalProperties: true
        meta:
          $ref: '#/components/schemas/ApiMeta'
    FinancialComparabilityReason:
      type: object
      required:
      - code
      - category
      - status
      - left
      - right
      - message
      properties:
        code:
          type: string
        category:
          type: string
        status:
          type: string
          enum:
          - same
          - different
          - unknown
          - observation
        left: {}
        right: {}
        message:
          type: string
        blocking:
          type: boolean
          description: Present on a candidate issue; whether unresolved candidate metadata prevents scalar resolution
    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'
    FinancialComparabilityReview:
      type: object
      description: All-pairs review of a bounded candidate set. Reported numeric text is normalized without currency or scale conversion. Different rounding declarations may explain a disagreement but never resolve it. same_observed_value records exact numeric agreement while financial comparability remains a separate analyst determination. selectedFactId and value remain null in this read-only review, including when observed values are the same.
      required:
      - schemaVersion
      - scope
      - reviewState
      - selectedFactId
      - value
      - candidates
      - comparisons
      - summary
      - bounds
      - limitations
      properties:
        schemaVersion:
          type: string
          const: filingsift-financial-comparability-v1
        scope:
          type: object
          description: Echoed normalized review scope; not an immutable data edition
          required:
          - cik
          - standardConcept
          - periodEnd
          - limit
          - order
          properties:
            cik:
              type: string
              pattern: ^[0-9]{10}$
            standardConcept:
              type: string
            periodEnd:
              type:
              - string
              - 'null'
              format: date
            limit:
              type: integer
              minimum: 1
              maximum: 100
            order:
              type: string
              const: fact_id_ascending
        reviewState:
          type: string
          enum:
          - insufficient_facts
          - unresolved_value_conflict
          - scope_difference
          - insufficient_metadata
          - same_observed_value
        selectedFactId:
          type: 'null'
        value:
          type: 'null'
        candidates:
          type: array
          maxItems: 100
          items:
            type: object
            required:
            - candidateId
            - sourceFact
            - normalizedNumericValue
            - valueState
            - issues
            properties:
              candidateId:
                type: string
              sourceFact:
                type: object
                additionalProperties: true
                description: Unmodified source fact retaining its accession, SEC/evidence provenance, exact parsed context, unit, taxonomy/mapping metadata and verification state; missing metadata is not invented
              normalizedNumericValue:
                type:
                - string
                - 'null'
              valueState:
                type: string
                enum:
                - numeric
                - nil
                - missing
                - invalid
                - unsafe_numeric_input
              issues:
                type: array
                items:
                  allOf:
                  - $ref: '#/components/schemas/FinancialComparabilityReason'
                  - type: object
                    required:
                    - blocking
        comparisons:
          type: array
          maxItems: 200
          description: Prioritized sample ordered by value conflict, scope difference, insufficient metadata, then same observed value, with stable input-index ties
          items:
            type: object
            required:
            - comparisonId
            - leftCandidateId
            - rightCandidateId
            - leftFactId
            - rightFactId
            - reviewState
            - selectedFactId
            - value
            - reasons
            properties:
              comparisonId:
                type: string
              leftCandidateId:
                type: string
              rightCandidateId:
                type: string
              leftFactId:
                type:
                - string
                - 'null'
              rightFactId:
                type:
                - string
                - 'null'
              reviewState:
                type: string
                enum:
                - unresolved_value_conflict
                - scope_difference
                - insufficient_metadata
                - same_observed_value
              selectedFactId:
                type: 'null'
              value:
                type: 'null'
              reasons:
                type: array
                items:
                  $ref: '#/components/schemas/FinancialComparabilityReason'
        summary:
          type: object
          description: Counts all pairs evaluated within the bounded candidate set, including pair details omitted from comparisons
          required:
          - factCount
          - comparisonCount
          - unresolvedPairCount
          - scopeDifferencePairCount
          - insufficientMetadataPairCount
          - sameObservedValuePairCount
          properties:
            factCount:
              type: integer
              minimum: 0
              maximum: 100
            comparisonCount:
              type: integer
              minimum: 0
              maximum: 4950
            unresolvedPairCount:
              type: integer
              minimum: 0
              maximum: 4950
            scopeDifferencePairCount:
              type: integer
              minimum: 0
              maximum: 4950
            insufficientMetadataPairCount:
              type: integer
              minimum: 0
              maximum: 4950
            sameObservedValuePairCount:
              type: integer
              minimum: 0
              maximum: 4950
        bounds:
          type: object
          required:
          - maximumFacts
          - maximumComparisons
          - maximumReturnedComparisons
          - returnedComparisonCount
          - comparisonsTruncated
          - inputTruncated
          properties:
            maximumFacts:
              type: integer
              const: 100
            maximumComparisons:
              type: integer
              const: 4950
            maximumReturnedComparisons:
              type: integer
              const: 200
            returnedComparisonCount:
              type: integer
              minimum: 0
              maximum: 200
            comparisonsTruncated:
              type: boolean
            inputTruncated:
              type: boolean
        limitations:
          type: array
          items:
            type: string
    FinancialComparabilityResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          $ref: '#/components/schemas/FinancialComparabilityReview'
        meta:
          $ref: '#/components/schemas/ApiMeta'
  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'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid filter, cursor, request, or query cost
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  headers:
    RateLimitReset:
      description: Seconds until the current fixed window resets
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests remaining in the current window
      schema:
        type: integer
    RetryAfter:
      description: Seconds before retrying
      schema:
        type: integer
    RateLimitLimit:
      description: Request limit for the current fixed window
      schema:
        type: integer
  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.