FilingSift Billing API

openapi: 3.2.0
info:
  title: FilingSift Billing 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: Billing
  description: Runtime plan catalog and provider-controlled checkout availability
paths:
  /billing/catalog:
    get:
      tags:
      - Billing
      operationId: getBillingCatalog
      summary: Get plans and self-service billing availability
      description: Returns the runtime monthly price and packaging catalog. All self-service plans share the published capability groups and differ by server-enforced capacity limits. providerEnabled and pricingStatus reflect configured provider and commercial activation; each plan has purchaseAvailable. Professional and Team require coverage review before new purchase and return purchaseAvailable=false; existing subscription entitlements remain valid. Consumers must read these flags rather than assume checkout is always enabled or disabled. seatBillingEnabled separately reports configured additional-seat billing.
      responses:
        '200':
          description: Billing catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCatalogResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
  /billing/webhooks/provider:
    post:
      tags:
      - Billing
      operationId: receiveBillingWebhook
      summary: Receive a signed event from the configured billing provider
      description: Verifies the configured provider signature over the raw request body and synchronizes subscription state. Stripe uses Stripe-Signature; the deterministic non-Stripe provider uses X-Billing-Signature. The configured provider's signature is required; bearer API keys do not authenticate this endpoint.
      parameters:
      - in: header
        name: Stripe-Signature
        description: Required when Stripe is the configured provider
        schema:
          type: string
      - in: header
        name: X-Billing-Signature
        description: Required for the deterministic non-Stripe provider
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '202':
          description: Verified event accepted idempotently
        '400':
          $ref: '#/components/responses/BadRequest'
  /account/billing:
    get:
      tags:
      - Billing
      operationId: getAccountBilling
      summary: Get entitlement, runtime catalog, subscription state, and invoices
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      responses:
        '200':
          description: Current billing state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBillingResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /account/billing/invoices:
    get:
      tags:
      - Billing
      operationId: listAccountInvoices
      summary: List bounded provider-hosted invoice and receipt metadata
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      responses:
        '200':
          description: Invoice history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /account/billing/checkout:
    post:
      tags:
      - Billing
      operationId: createBillingCheckout
      summary: Create hosted checkout for an available paid plan
      description: New Professional and Team purchases return 409 coverage_review_required before a provider session is created. Builder remains available when commercial billing is active.
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - planKey
              properties:
                planKey:
                  type: string
                  enum:
                  - builder
                  - professional
                  - team
      responses:
        '201':
          description: Provider-hosted checkout session
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /account/billing/seats:
    patch:
      tags:
      - Billing
      operationId: updateBillingSeats
      summary: Update seats within the plan/member bounds with immediate Stripe proration
      description: Available only when commercial billing and a separate additional-seat Price are configured. Check catalog.seatBillingEnabled; the base flat-plan subscription item stays at quantity one.
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - quantity
              properties:
                quantity:
                  type: integer
                  minimum: 1
      responses:
        '202':
          description: Prorated seat update accepted
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /account/billing/portal:
    post:
      tags:
      - Billing
      operationId: createBillingPortal
      summary: Create a provider-hosted customer portal session
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      responses:
        '201':
          description: Provider-hosted portal session
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /account/billing/cancel:
    post:
      tags:
      - Billing
      operationId: cancelBillingSubscription
      summary: Request subscription cancellation now or at period end
      security:
      - ApiKeyAuth: []
      - BrowserSession: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                atPeriodEnd:
                  type: boolean
                  default: true
      responses:
        '200':
          description: Cancellation request accepted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  headers:
    RateLimitReset:
      description: Seconds until the current fixed window resets
      schema:
        type: integer
    RetryAfter:
      description: Seconds before retrying
      schema:
        type: integer
    RateLimitLimit:
      description: Request limit for the current fixed window
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests remaining in the current window
      schema:
        type: integer
  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'
    Conflict:
      description: Requested account transition violates a current-state constraint
      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'
    Unauthorized:
      description: Missing, malformed, expired, revoked, or invalid account session/API key, or incorrect login credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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'
    BadRequest:
      description: Invalid filter, cursor, request, or query cost
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    InvoiceListResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Invoice'
        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
    BillingSubscription:
      type: object
      properties:
        orgId:
          type: string
          format: uuid
        planKey:
          $ref: '#/components/schemas/PlanKey'
        status:
          type: string
          enum:
          - active
          - trialing
          - past_due
          - incomplete
          - canceled
          - unpaid
        currentPeriodEnd:
          type:
          - string
          - 'null'
          format: date-time
        cancelAtPeriodEnd:
          type: boolean
        graceEndsAt:
          type:
          - string
          - 'null'
          format: date-time
        seatQuantity:
          type: integer
          minimum: 1
    BillingCatalogResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          $ref: '#/components/schemas/BillingCatalog'
        meta:
          $ref: '#/components/schemas/ApiMeta'
    Plan:
      type: object
      required:
      - key
      - label
      - monthlyRequests
      - monthlyQueryCost
      - companyLimit
      - historyDays
      - activeApiKeyLimit
      - memberLimit
      - activeSessionLimit
      - pendingOnboardingLimit
      properties:
        key:
          $ref: '#/components/schemas/PlanKey'
        label:
          type: string
        monthlyRequests:
          type: integer
          minimum: 1
        monthlyQueryCost:
          type: integer
          minimum: 1
        companyLimit:
          type: integer
          minimum: 1
        historyDays:
          type: integer
          minimum: 1
          description: Maximum accessible filing history in days; actual availability remains subject to indexed coverage.
        activeApiKeyLimit:
          type: integer
          minimum: 1
        memberLimit:
          type: integer
          minimum: 1
        activeSessionLimit:
          type: integer
          minimum: 1
        pendingOnboardingLimit:
          type: integer
          minimum: 1
    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'
    BillingAccess:
      type: object
      required:
      - requestedPlanKey
      - effectivePlanKey
      - status
      - entitled
      properties:
        requestedPlanKey:
          $ref: '#/components/schemas/PlanKey'
        effectivePlanKey:
          $ref: '#/components/schemas/PlanKey'
        status:
          type: string
        entitled:
          type: boolean
        reason:
          type:
          - string
          - 'null'
        currentPeriodEnd:
          type:
          - string
          - 'null'
          format: date-time
        cancelAtPeriodEnd:
          type: boolean
        graceEndsAt:
          type:
          - string
          - 'null'
          format: date-time
        subscription:
          oneOf:
          - $ref: '#/components/schemas/BillingSubscription'
          - type: 'null'
    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'
    Invoice:
      type: object
      required:
      - id
      - orgId
      - status
      - amountDueCents
      - amountPaidCents
      - currency
      - createdAt
      properties:
        id:
          type: string
          format: uuid
        orgId:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - paid
          - open
          - void
        amountDueCents:
          type: integer
          minimum: 0
        amountPaidCents:
          type: integer
          minimum: 0
        currency:
          type: string
          pattern: ^[A-Z]{3}$
        hostedInvoiceUrl:
          type:
          - string
          - 'null'
          format: uri
        receiptUrl:
          type:
          - string
          - 'null'
          format: uri
        periodStart:
          type:
          - string
          - 'null'
          format: date-time
        periodEnd:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    AccountBillingResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          allOf:
          - $ref: '#/components/schemas/BillingAccess'
          - type: object
            required:
            - catalog
            - invoices
            properties:
              catalog:
                $ref: '#/components/schemas/BillingCatalog'
              invoices:
                type: array
                items:
                  $ref: '#/components/schemas/Invoice'
        meta:
          $ref: '#/components/schemas/ApiMeta'
    BillingCatalog:
      type: object
      required:
      - modelVersion
      - pricingStatus
      - packagingModel
      - billingInterval
      - primaryMetric
      - capabilityGroups
      - comparisonMetrics
      - dataRights
      - providerEnabled
      - seatBillingEnabled
      - plans
      properties:
        modelVersion:
          type: string
        pricingStatus:
          type: string
          enum:
          - available
          - unavailable
        packagingModel:
          type: string
          const: shared_capabilities_capacity_tiers
        billingInterval:
          type: string
          const: month
        primaryMetric:
          type: string
          const: monitored_companies
        capabilityGroups:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - key
            - label
            - summary
            - items
            properties:
              key:
                type: string
                enum:
                - research
                - financing
                - workflow
                - trust
              label:
                type: string
              summary:
                type: string
              items:
                type: array
                minItems: 1
                items:
                  type: string
        comparisonMetrics:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - key
            - group
            - label
            - format
            - enforced
            properties:
              key:
                type: string
                enum:
                - companyLimit
                - historyDays
                - pendingOnboardingLimit
                - monthlyRequests
                - monthlyQueryCost
                - memberLimit
                - activeApiKeyLimit
                - activeSessionLimit
              group:
                type: string
                enum:
                - Coverage
                - Usage
                - Workspace
              label:
                type: string
              format:
                type: string
                enum:
                - integer
                - duration_days
              enforced:
                type: boolean
                const: true
        guardrails:
          type: array
          items:
            type: string
        eventDeliveryMeteredSeparately:
          type: boolean
        historicalBackfills:
          type: string
        redistribution:
          type: string
        dataRights:
          type: object
          additionalProperties: true
          description: Same machine-readable license-free source boundary published by /meta.
        providerEnabled:
          type: boolean
        seatBillingEnabled:
          type: boolean
          description: True only when an approved separate additional-seat Stripe Price is configured.
        plans:
          type: array
          items:
            $ref: '#/components/schemas/BillingPlan'
    PlanKey:
      type: string
      enum:
      - evaluation
      - builder
      - professional
      - team
      - internal
    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'
    BillingPlan:
      allOf:
      - $ref: '#/components/schemas/Plan'
      - type: object
        required:
        - displayName
        - monthlyPriceCents
        - currency
        - audience
        - summary
        - recommended
        - purchaseAvailable
        properties:
          displayName:
            type: string
          monthlyPriceCents:
            type: integer
            minimum: 0
          currency:
            type: string
            const: USD
          audience:
            type: string
          summary:
            type: string
          recommended:
            type: boolean
          purchaseAvailable:
            type: boolean
          purchaseReviewRequired:
            type: boolean
            description: A coverage and capacity review is required before new purchase.
          purchaseAvailabilityReason:
            type:
            - string
            - 'null'
            enum:
            - coverage_review_required
            - null
  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.