FilingSift Integrations API

openapi: 3.2.0
info:
  title: FilingSift Integrations 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: Integrations
  description: Private feeds
  collaboration delivery: null
  customer exports: null
  dashboards: null
  mobile triage: null
  and enterprise identity readiness: null
paths:
  /feeds/{token}/{format}:
    get:
      tags:
      - Integrations
      operationId: readPrivateMonitoringFeed
      summary: Read a revocable RSS or Atom monitoring feed
      security: []
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
      - name: format
        in: path
        required: true
        schema:
          type: string
          enum:
          - rss
          - atom
      responses:
        '200':
          description: Private evidence-linked monitoring feed
        '404':
          $ref: '#/components/responses/NotFound'
  /account/integrations:
    get:
      tags:
      - Integrations
      operationId: getIntegrationOverview
      summary: List feeds, channels, destinations, export jobs, dashboards, caps, and provider…
      security:
      - BrowserSession: []
      responses:
        '200':
          description: Integration overview
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /account/integrations/feed:
    post:
      tags:
      - Integrations
      operationId: rotateMonitoringFeed
      summary: Revoke the prior feed token and display a replacement once
      security:
      - BrowserSession: []
      responses:
        '201':
          description: One-time feed token and RSS and Atom paths
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      tags:
      - Integrations
      operationId: revokeMonitoringFeed
      summary: Revoke the active private feed token
      security:
      - BrowserSession: []
      responses:
        '204':
          description: Feed revoked
  /account/integrations/channels:
    post:
      tags:
      - Integrations
      operationId: createDeliveryChannel
      summary: Store an encrypted provider-bound Slack or Teams webhook
      security:
      - BrowserSession: []
      responses:
        '201':
          description: Channel created and URL never returned
        '409':
          $ref: '#/components/responses/Conflict'
  /account/integrations/channels/{id}:
    delete:
      tags:
      - Integrations
      operationId: deleteDeliveryChannel
      summary: Remove a collaboration delivery channel
      security:
      - BrowserSession: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Channel removed
        '404':
          $ref: '#/components/responses/NotFound'
  /account/integrations/channels/{id}/test:
    post:
      tags:
      - Integrations
      operationId: testDeliveryChannel
      summary: Send a bounded test alert to a configured channel
      security:
      - BrowserSession: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Test delivered
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /account/integrations/destinations:
    post:
      tags:
      - Integrations
      operationId: createExportDestination
      summary: Configure customer S3 or Google Sheets delivery
      security:
      - BrowserSession: []
      responses:
        '201':
          description: S3 or Google Sheets destination created; S3 external ID displayed once
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
  /account/integrations/destinations/{id}:
    delete:
      tags:
      - Integrations
      operationId: deleteExportDestination
      summary: Remove an export destination
      security:
      - BrowserSession: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Destination removed
        '404':
          $ref: '#/components/responses/NotFound'
  /account/integrations/exports:
    post:
      tags:
      - Integrations
      operationId: queueCustomerExport
      summary: Queue a bounded monitoring export to a configured destination
      security:
      - BrowserSession: []
      responses:
        '202':
          description: Export queued
        '409':
          $ref: '#/components/responses/Conflict'
  /account/integrations/dashboards:
    post:
      tags:
      - Integrations
      operationId: createCustomDashboard
      summary: Create a personal or shared dashboard with bounded calculated fields
      security:
      - BrowserSession: []
      responses:
        '201':
          description: Dashboard created
        '409':
          $ref: '#/components/responses/Conflict'
  /account/integrations/dashboards/{id}:
    delete:
      tags:
      - Integrations
      operationId: deleteCustomDashboard
      summary: Remove a dashboard created by the current user
      security:
      - BrowserSession: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Dashboard removed
        '404':
          $ref: '#/components/responses/NotFound'
  /account/integrations/calculated-fields/preview:
    post:
      tags:
      - Integrations
      operationId: previewCalculatedField
      summary: Evaluate bounded arithmetic; missing inputs and division by zero return null
      security:
      - BrowserSession: []
      responses:
        '200':
          description: Nullable numeric preview
        '400':
          $ref: '#/components/responses/BadRequest'
  /account/mobile/alerts:
    get:
      tags:
      - Integrations
      operationId: listMobileAlertTriage
      summary: List recent organization alerts with user-specific triage state
      security:
      - BrowserSession: []
      responses:
        '200':
          description: Mobile alert queue
  /account/mobile/alerts/{id}:
    patch:
      tags:
      - Integrations
      operationId: triageMobileAlert
      summary: Acknowledge or dismiss one organization alert for the current user
      security:
      - BrowserSession: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Triage state updated
        '404':
          $ref: '#/components/responses/NotFound'
  /account/enterprise-identity:
    get:
      tags:
      - Integrations
      operationId: getEnterpriseIdentityReadiness
      summary: Return demand-gated OIDC and SCIM activation state
      security:
      - BrowserSession: []
      responses:
        '200':
          description: Enterprise identity readiness with no unapproved connector activated
  /account/enterprise-controls:
    get:
      tags:
      - Integrations
      operationId: getEnterpriseControlReadiness
      summary: Return the organization enterprise-demand receipt and truthful per-control…
      description: Controlled pilots remain available without enterprise procurement. Browser owner or admin session required; no secret identity metadata or assessment report is returned.
      security:
      - BrowserSession: []
      responses:
        '200':
          description: Enterprise demand
          identity activation flags: null
          and fail-closed readiness: null
  /account/enterprise-controls/requests:
    post:
      tags:
      - Integrations
      operationId: recordEnterpriseControlDemand
      summary: Append a bounded organization enterprise-demand receipt without activating any…
      description: Records requested OIDC SSO, SCIM, independent penetration test, SOC 2 path, contractual support, or SLA needs. This endpoint does not create a contract, certification, assessment, or service commitment.
      security:
      - BrowserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - requestedControls
              properties:
                requestedControls:
                  type: array
                  minItems: 1
                  maxItems: 6
                  uniqueItems: true
                  items:
                    type: string
                    enum:
                    - oidc_sso
                    - scim
                    - independent_penetration_test
                    - soc2
                    - contractual_support
                    - sla
                identityProvider:
                  type: string
                  enum:
                  - okta
                  - microsoft_entra_id
                  - google_workspace
                  - ping_identity
                  - other
                  - unspecified
                estimatedSeats:
                  type: string
                  enum:
                  - 125
                  - 26100
                  - 101500
                  - 500_plus
                  - unspecified
                targetQuarter:
                  type:
                  - string
                  - 'null'
                  pattern: ^20[0-9]{2}-Q[1-4]$
                supportWindow:
                  type: string
                  enum:
                  - business_hours
                  - extended_hours
                  - 24x7
                  - unspecified
                note:
                  type: string
                  maxLength: 1000
      responses:
        '201':
          description: Append-only demand receipt created; no enterprise control activated
        '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'
    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'
    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.