FilingSift Corporate Events API

openapi: 3.2.0
info:
  title: FilingSift Corporate Events 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: Corporate Events
  description: Deployed public ownership and event queries. Supplied credentials require search:read and billing access; the current router does not apply watchlist or plan-history filters.
paths:
  /corporate-events/vocabulary:
    get:
      tags:
      - Corporate Events
      operationId: getCorporateEventVocabulary
      summary: List corporate-event domains and issuer-history views
      responses:
        '200':
          description: Supported domains
          views: null
          and verification states: null
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /corporate-events/query:
    post:
      tags:
      - Corporate Events
      operationId: queryCorporateEvents
      summary: Query source-linked ownership, governance, compensation, offering, and…
      description: Public query with optional credentials; supplied credentials require search:read and billing access. No watchlist or plan-history filter is applied. Follow request-bound data.pagination.nextCursor; candidate observations are source-linked and ready for analyst review.
      security:
      - {}
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  maxLength: 300
                filters:
                  type: object
                  additionalProperties: true
                cursor:
                  type: string
                limit:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 50
      responses:
        '200':
          description: Request-bound cursor page with exact filing provenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
  /corporate-events/coverage:
    get:
      tags:
      - Corporate Events
      operationId: getCorporateEventCoverage
      summary: Get extraction counts, freshest dates, and known gaps by form and issuer
      description: Public event counts by domain and filing/extracted-filing/event/known-gap counts by form and issuer. This is not a reviewed accuracy rate. Optional credentials require search:read and billing access.
      security:
      - {}
      - ApiKeyAuth: []
      responses:
        '200':
          description: Domain
          form: null
          and issuer coverage with explicit known gaps: null
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /corporate-events/issuers/{ticker}/{view}:
    get:
      tags:
      - Corporate Events
      operationId: getIssuerCorporateEventHistory
      summary: Get a source-linked issuer ownership, compensation, governance…
      description: Public history with a default of 50 and maximum of 100 observations per page. Optional credentials require search:read and billing access; no account-history or watchlist restriction is applied.
      security:
      - {}
      - ApiKeyAuth: []
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
      - name: view
        in: path
        required: true
        schema:
          type: string
          enum:
          - insider-transactions
          - beneficial-ownership
          - institutional-holdings
          - compensation
          - governance
          - capital-markets
          - transactions
      - name: query
        in: query
        schema:
          type: string
          maxLength: 300
      - name: cursor
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Cursor-paginated issuer history with exact source evidence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '404':
          $ref: '#/components/responses/NotFound'
  /corporate-events/export:
    post:
      tags:
      - Corporate Events
      operationId: exportCorporateEvents
      summary: Export one source-linked cursor chunk as CSV or NDJSON
      description: Same optional authentication as corporate-event queries. Accepts query, filters, cursor, limit, and format in a JSON body; exports at most 100 observations and preserves evidence. Follow X-Next-Cursor while X-Export-Truncated is true.
      security:
      - {}
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  maxLength: 300
                filters:
                  type: object
                  additionalProperties: true
                cursor:
                  type: string
                limit:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 100
                format:
                  type: string
                  enum:
                  - csv
                  - ndjson
                  default: csv
      responses:
        '200':
          description: Export with row count
          truncation: null
          next cursor: null
          and SHA-256 headers: null
        '400':
          $ref: '#/components/responses/BadRequest'
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'
    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'
    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.