FilingSift Pilots API

openapi: 3.2.0
info:
  title: FilingSift Pilots 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: Pilots
  description: Private consented pilot enrollment
  paired workflow observations: null
  evidence and fact audits: null
  return-use measurement: null
  and completion review: null
paths:
  /account/pilots:
    get:
      tags:
      - Pilots
      operationId: listOrganizationPilots
      summary: Return the signed-in organization's private pilot ledger and aggregate
      description: Browser session required. The response measures paired task time, missed evidence, unsupported facts, and observed return use. It is not a public customer or product-performance claim.
      security:
      - BrowserSession: []
      responses:
        '200':
          description: Organization-scoped private pilot portfolio
        '403':
          $ref: '#/components/responses/Forbidden'
  /account/pilots/{pilot_id}/observations:
    post:
      tags:
      - Pilots
      operationId: recordPilotObservation
      summary: Append one paired task and evidence/fact audit observation
      security:
      - BrowserSession: []
      parameters:
      - name: pilot_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - eventType
              - issuerAlias
              - minutesWithoutFilingSift
              - minutesWithFilingSift
              - expectedEvidenceCount
              - missedEvidenceCount
              - assertedFactCount
              - unsupportedFactCount
              properties:
                observedAt:
                  type: string
                  format: date-time
                  description: Defaults to server time; limited to the prior 90 days and five minutes into the future.
                eventType:
                  type: string
                  minLength: 1
                  maxLength: 80
                issuerAlias:
                  type: string
                  minLength: 1
                  maxLength: 80
                minutesWithoutFilingSift:
                  type: number
                  exclusiveMinimum: 0
                  maximum: 1440
                minutesWithFilingSift:
                  type: number
                  exclusiveMinimum: 0
                  maximum: 1440
                expectedEvidenceCount:
                  type: integer
                  minimum: 0
                  maximum: 10000
                missedEvidenceCount:
                  type: integer
                  minimum: 0
                  maximum: 10000
                assertedFactCount:
                  type: integer
                  minimum: 0
                  maximum: 10000
                unsupportedFactCount:
                  type: integer
                  minimum: 0
                  maximum: 10000
                accession:
                  type: string
                  pattern: ^[0-9]{10}-[0-9]{2}-[0-9]{6}$
                filingUrl:
                  type: string
                  format: uri
                evidenceText:
                  type: string
                  minLength: 1
                  maxLength: 2000
                verificationState:
                  type: string
                  enum:
                  - machine_checked
                  - human_verified
                  - rejected
                  - uncertain
                decisionRelevant:
                  type:
                  - boolean
                  - 'null'
                note:
                  type: string
                  maxLength: 1000
      responses:
        '201':
          description: Append-only observation recorded
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
  /admin/pilots:
    get:
      tags:
      - Pilots
      operationId: listPilotPortfolio
      summary: Return the private cross-organization pilot portfolio and three-pilot threshold
      security:
      - BrowserSession: []
      responses:
        '200':
          description: Private pilot portfolio
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags:
      - Pilots
      operationId: enrollPilot
      summary: Enroll an organization after measurement consent is recorded
      security:
      - BrowserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - organizationId
              - label
              - workflow
              - analystRole
              - consentRecorded
              properties:
                organizationId:
                  type: string
                  format: uuid
                label:
                  type: string
                  minLength: 1
                  maxLength: 100
                workflow:
                  type: string
                  enum:
                  - financing_change_review
                  - filing_comparison
                  - evidence_export
                  - api_integration
                analystRole:
                  type: string
                  enum:
                  - credit_analyst
                  - research_analyst
                  - financial_analyst
                  - developer
                  - other
                consentRecorded:
                  type: boolean
                  const: true
      responses:
        '201':
          description: Private active pilot enrolled
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /admin/pilots/{pilot_id}/reviews:
    post:
      tags:
      - Pilots
      operationId: reviewPilot
      summary: Append a completed or withdrawn final review
      description: Completion fails until paired time, nonzero evidence and fact denominators, and returned or seven-day no-return behavior are observable.
      security:
      - BrowserSession: []
      parameters:
      - name: pilot_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '201':
          description: Append-only final review recorded
        '409':
          $ref: '#/components/responses/Conflict'
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'
    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'
    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.