FilingSift Security API

openapi: 3.2.0
info:
  title: FilingSift Security 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: Security
  description: MFA factors
  passkeys: null
  and active browser sessions: null
paths:
  /auth/mfa/verify:
    post:
      tags:
      - Security
      operationId: verifyLoginMfa
      summary: Complete a password-authenticated login with TOTP or a verified passkey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - challengeToken
              properties:
                challengeToken:
                  type: string
                totpCode:
                  type: string
                  pattern: ^[0-9]{6}$
                passkeyResponse:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Browser session created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /account/security:
    get:
      tags:
      - Security
      operationId: getAccountSecurityFactors
      summary: List TOTP status and registered passkeys
      security:
      - BrowserSession: []
      responses:
        '200':
          description: Security-factor inventory
  /account/security/totp:
    post:
      tags:
      - Security
      operationId: beginTotpSetup
      summary: Begin encrypted TOTP enrollment and return the secret once
      security:
      - BrowserSession: []
      responses:
        '201':
          description: Pending TOTP setup
    delete:
      tags:
      - Security
      operationId: disableTotp
      summary: Disable TOTP after verifying a fresh code
      security:
      - BrowserSession: []
      responses:
        '200':
          description: TOTP disabled
  /account/security/totp/verify:
    post:
      tags:
      - Security
      operationId: verifyTotpSetup
      summary: Verify and activate a pending TOTP factor
      security:
      - BrowserSession: []
      responses:
        '200':
          description: TOTP enabled
  /account/security/reauth/options:
    post:
      tags:
      - Security
      operationId: beginSecurityReauthentication
      summary: Confirm the current password for one passkey change
      description: Browser session and cookie CSRF protections apply. If a factor is enrolled, returns an existing-factor MFA challenge instead of a grant. Confirmation is bound to the user, organization, current session, selected action, target passkey, and credential state; expires five minutes after password confirmation.
      security:
      - BrowserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - currentPassword
              - action
              properties:
                currentPassword:
                  type: string
                  maxLength: 128
                  writeOnly: true
                action:
                  type: string
                  enum:
                  - passkey_add
                  - passkey_remove
                passkeyId:
                  type: string
                  format: uuid
                  description: Required when action is passkey_remove
      responses:
        '200':
          description: Envelope containing one-time reauthToken and expiresAt when no MFA factor is enrolled
        '202':
          description: Envelope containing required true
          challengeToken: null
          methods and optional passkeyOptions; complete reauth/verify: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Incorrect password or changed account security state
        '403':
          description: Browser session or exact-origin CSRF protection required
        '429':
          description: Authentication or credential-change rate limit reached
  /account/security/reauth/verify:
    post:
      tags:
      - Security
      operationId: verifySecurityReauthentication
      summary: Prove an existing factor before changing passkeys
      description: Accepts only a reauthentication challenge from the current browser session, never a login challenge. Does not create a login session. Submit either a fresh authenticator code or an existing passkey assertion.
      security:
      - BrowserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - challengeToken
              properties:
                challengeToken:
                  type: string
                totpCode:
                  type: string
                  pattern: ^[0-9]{6}$
                passkeyResponse:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Envelope containing one-time reauthToken and expiresAt
        '400':
          description: Invalid
          expired: null
          used: null
          or wrong-purpose MFA challenge: null
        '401':
          description: Incorrect factor
          wrong session: null
          or changed credential state: null
        '403':
          description: Browser session or exact-origin CSRF protection required
        '429':
          description: Authentication or credential-change rate limit reached
  /account/security/passkeys/options:
    post:
      tags:
      - Security
      operationId: beginPasskeyRegistration
      summary: Consume fresh confirmation to create a session-bound WebAuthn registration…
      description: Requires an unused passkey_add reauthToken from the same session. The challenge retains the confirmation deadline and becomes unusable after password reset/change or session revocation.
      security:
      - BrowserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - reauthToken
              properties:
                reauthToken:
                  type: string
                  writeOnly: true
      responses:
        '200':
          description: WebAuthn creation options
        '401':
          description: Fresh confirmation required or account security changed
  /account/security/passkeys:
    post:
      tags:
      - Security
      operationId: finishPasskeyRegistration
      summary: Verify and store a passkey public credential
      description: Requires an unused registration challenge created by this session after fresh confirmation. Rechecks credential and session state atomically with registration.
      security:
      - BrowserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - response
              properties:
                response:
                  type: object
                  additionalProperties: true
                displayName:
                  type: string
                  maxLength: 120
      responses:
        '201':
          description: Passkey registered
        '400':
          description: Invalid or expired registration challenge
        '401':
          description: Fresh confirmation required or account security changed
  /account/security/passkeys/{passkeyId}:
    delete:
      tags:
      - Security
      operationId: deletePasskey
      summary: Remove a user-owned passkey after fresh confirmation
      description: Requires an unused passkey_remove reauthToken bound to this exact passkey and session. An existing factor is required when enrolled, including when removing the last passkey.
      security:
      - BrowserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - reauthToken
              properties:
                reauthToken:
                  type: string
                  writeOnly: true
      parameters:
      - in: path
        name: passkeyId
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Passkey removed
        '401':
          description: Fresh confirmation required or account security changed
  /account/sessions:
    get:
      tags:
      - Security
      operationId: listAccountSessions
      summary: List active browser sessions and identify the current session
      security:
      - BrowserSession: []
      responses:
        '200':
          description: Active session inventory
  /account/sessions/{sessionId}:
    delete:
      tags:
      - Security
      operationId: revokeAccountSession
      summary: Remotely revoke another active browser session
      security:
      - BrowserSession: []
      parameters:
      - in: path
        name: sessionId
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Session revoked
        '409':
          $ref: '#/components/responses/Conflict'
  /account/email:
    patch:
      tags:
      - Security
      operationId: changeAccountEmail
      summary: Change the signed-in user's email and send a new verification message
      security:
      - BrowserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - email
              - currentPassword
              properties:
                email:
                  type: string
                  format: email
                  maxLength: 254
                currentPassword:
                  type: string
                  minLength: 1
                  maxLength: 128
                  writeOnly: true
      responses:
        '202':
          description: Change accepted; verification is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /account/password:
    patch:
      tags:
      - Security
      operationId: changeAccountPassword
      summary: Replace the signed-in user's password and revoke all active browser sessions
      security:
      - BrowserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - currentPassword
              - password
              properties:
                currentPassword:
                  type: string
                  minLength: 1
                  maxLength: 128
                  writeOnly: true
                password:
                  type: string
                  minLength: 12
                  maxLength: 128
                  writeOnly: true
      responses:
        '204':
          description: Password changed; all active browser sessions and action tokens revoked
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
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'
    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'
    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.