FilingSift Team API

openapi: 3.2.0
info:
  title: FilingSift Team 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: Team
  description: Invitations
  organization policy: null
  shared review queues: null
  usage forecasts: null
  and audit export: null
paths:
  /team/invitations/accept:
    post:
      tags:
      - Team
      operationId: acceptTeamInvitation
      summary: Consume a single-use invitation and create a session in the invited organization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - token
              - displayName
              - password
              properties:
                token:
                  type: string
                displayName:
                  type: string
                  maxLength: 120
                password:
                  type: string
                  minLength: 12
                  maxLength: 128
      responses:
        '201':
          description: Invitation accepted and browser session created
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
  /account/team:
    get:
      tags:
      - Team
      operationId: getTeamWorkspace
      summary: Get team policy, invitations, review queue, and usage forecast
      security:
      - BrowserSession: []
      responses:
        '200':
          description: Team workspace state
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /account/team/settings:
    patch:
      tags:
      - Team
      operationId: updateTeamSettings
      summary: Configure allowed email domains and usage-alert thresholds
      security:
      - BrowserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                allowedEmailDomains:
                  type: array
                  maxItems: 20
                  items:
                    type: string
                usageAlertThresholds:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: integer
                    minimum: 1
                    maximum: 100
      responses:
        '200':
          description: Team policy updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
  /account/team/invitations:
    post:
      tags:
      - Team
      operationId: createTeamInvitation
      summary: Send a domain-checked single-use member invitation
      security:
      - BrowserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - role
              properties:
                email:
                  type: string
                  format: email
                role:
                  $ref: '#/components/schemas/MembershipRole'
      responses:
        '201':
          description: Invitation stored and email delivered
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /account/team/invitations/{invitationId}:
    delete:
      tags:
      - Team
      operationId: revokeTeamInvitation
      summary: Revoke a pending invitation
      security:
      - BrowserSession: []
      parameters:
      - in: path
        name: invitationId
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Invitation revoked
        '404':
          $ref: '#/components/responses/NotFound'
  /account/team/reviews:
    post:
      tags:
      - Team
      operationId: createTeamReview
      summary: Create a filing review assignment
      security:
      - BrowserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - accession
              - title
              properties:
                accession:
                  type: string
                title:
                  type: string
                  maxLength: 200
                assignedUserId:
                  type:
                  - string
                  - 'null'
                  format: uuid
      responses:
        '201':
          description: Review task created
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
  /account/team/reviews/{reviewId}/versions:
    post:
      tags:
      - Team
      operationId: createTeamReviewVersion
      summary: Append an immutable review disposition version
      security:
      - BrowserSession: []
      parameters:
      - in: path
        name: reviewId
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '201':
          description: Review version appended
        '404':
          $ref: '#/components/responses/NotFound'
  /account/team/reviews/{reviewId}/history:
    get:
      tags:
      - Team
      operationId: getTeamReviewHistory
      summary: List immutable review versions
      security:
      - BrowserSession: []
      parameters:
      - in: path
        name: reviewId
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Ordered review version history
        '404':
          $ref: '#/components/responses/NotFound'
  /account/audit/export:
    get:
      tags:
      - Team
      operationId: exportAccountAudit
      summary: Export canonical append-only NDJSON with SHA-256 checksum headers
      security:
      - BrowserSession: []
      responses:
        '200':
          description: Immutable audit export
          content:
            application/x-ndjson:
              schema:
                type: string
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'
    MembershipRole:
      type: string
      enum:
      - owner
      - admin
      - member
      - viewer
  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'
    ServiceUnavailable:
      description: Turnstile, commercial billing, or another required service is temporarily or intentionally unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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'
    Unauthorized:
      description: Missing, malformed, expired, revoked, or invalid account session/API key, or incorrect login credentials
      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'
  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.