FactIQ Equities API

openapi: 3.2.0
info:
  title: FactIQ Equities API
  description: Programmatic access to curated economic time series data sourced from the BLS, Census, BEA, and OEWS pipelines. Endpoints cover direct series lookups, authentication, and MCP-based data tools for analysis.
  contact:
    name: FactIQ
    url: https://www.factiq.com/contact
  version: 1.0.0
tags:
- name: Equities
paths:
  /equities/watchlists:
    get:
      tags:
      - Equities
      summary: List Watchlists
      operationId: list_watchlists_equities_watchlists_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Watchlist'
                type: array
                title: Response List Watchlists Equities Watchlists Get
      security:
      - HTTPBearer: []
    post:
      tags:
      - Equities
      summary: Create Watchlist
      operationId: create_watchlist_equities_watchlists_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistCreate'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /equities/watchlists/{watchlist_id}:
    patch:
      tags:
      - Equities
      summary: Update Watchlist
      operationId: update_watchlist_equities_watchlists__watchlist_id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: integer
          title: Watchlist Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Equities
      summary: Delete Watchlist
      operationId: delete_watchlist_equities_watchlists__watchlist_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: integer
          title: Watchlist Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /equities/watchlists/{watchlist_id}/items:
    post:
      tags:
      - Equities
      summary: Add Watchlist Item
      operationId: add_watchlist_item_equities_watchlists__watchlist_id__items_post
      security:
      - HTTPBearer: []
      parameters:
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: integer
          title: Watchlist Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistItemCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /equities/watchlists/{watchlist_id}/items/{symbol}:
    delete:
      tags:
      - Equities
      summary: Remove Watchlist Item
      operationId: remove_watchlist_item_equities_watchlists__watchlist_id__items__symbol__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: integer
          title: Watchlist Id
      - name: symbol
        in: path
        required: true
        schema:
          type: string
          title: Symbol
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /equities/{ticker}/fundamentals:
    get:
      tags:
      - Equities
      summary: Company Fundamentals
      description: 'A single SEC fundamentals statement (income / balance sheet / cash flow)

        for a ticker, newest period first. Returns the same {columns, results, ...}

        payload the agent''s market-data tool serves, or an empty result set when we

        have no SEC coverage for this ticker/statement (the UI shows an empty

        state — we do NOT fall back to a different source for the deterministic

        table).'
      operationId: company_fundamentals_equities__ticker__fundamentals_get
      security:
      - HTTPBearer: []
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          title: Ticker
      - name: statement
        in: query
        required: false
        schema:
          type: string
          default: income_statement
          title: Statement
      - name: period
        in: query
        required: false
        schema:
          type: string
          default: quarterly
          title: Period
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /equities/{ticker}/segments:
    get:
      tags:
      - Equities
      summary: Company Segments
      description: 'Segment / product / geography breakdown of one SEC metric, pivoted wide

        (one column per member, newest period first) for stacked charting.


        Series IDs are not safely splittable (both metric_code and member names

        contain underscores), so members are resolved through unified series dimensions

        table: each breakdown series carries a `metric_code` dimension and a

        `_member` dimension. We also return every available

        (breakout, metric) combo so the UI can offer a picker.


        The company''s series are found through `filings.securities` (indexed on

        upper(ticker)) and `filings.source_series.issuer_id`, never by matching the

        series-id prefix: a prefix comparison cannot use an index and reads every

        dimension row in the schema (issue: the admin company page took minutes).'
      operationId: company_segments_equities__ticker__segments_get
      security:
      - HTTPBearer: []
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          title: Ticker
      - name: breakout
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Breakout
      - name: metric
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Metric
      - name: period
        in: query
        required: false
        schema:
          type: string
          default: quarterly
          title: Period
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /equities/{ticker}/transcripts:
    get:
      tags:
      - Equities
      summary: Company Transcripts
      description: 'Earnings-transcript intelligence for a ticker: the transcript list plus

        extracted claims and Q&A pressure points. Read-only from the `transcripts`

        schema on the DATA cluster. Note only structured claims are stored — there

        is no raw transcript text.'
      operationId: company_transcripts_equities__ticker__transcripts_get
      security:
      - HTTPBearer: []
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          title: Ticker
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /equities/{ticker}/kpis:
    get:
      tags:
      - Equities
      summary: Company Kpis
      description: 'All operational-KPI series for a ticker, grouped into chartable blocks —

        one block per (kpi_code, value_form, frequency), pivoted wide with one

        column per member, newest period first (same wide shape as /segments).

        Blocks with value_form=''yoy_change'' are management-stated percent changes,

        NOT levels (companies like SNDK only disclose the change). Also returns the

        discovery-profile state and per-filing extraction progress so the admin

        page can show pipeline status even before any series exist.'
      operationId: company_kpis_equities__ticker__kpis_get
      security:
      - HTTPBearer: []
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          title: Ticker
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /equities/{ticker}/kpis/provenance:
    get:
      tags:
      - Equities
      summary: Company Kpi Provenance
      description: 'Per-point provenance for one KPI block: the verbatim filing quote each

        value was re-parsed from (fact_lineage.context_ref) plus the source filing.

        Each row names its member as the /kpis column does ("Consolidated

        (Adjusted)" for an adjusted series) and its basis ("reported" when the

        series has no kpi_basis dimension).

        Fetched on demand by the admin UI when the user expands ''filing quotes'' —

        quotes are too heavy to inline into /kpis for every point.'
      operationId: company_kpi_provenance_equities__ticker__kpis_provenance_get
      security:
      - HTTPBearer: []
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          title: Ticker
      - name: kpi
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          title: Kpi
      - name: value_form
        in: query
        required: false
        schema:
          type: string
          default: absolute
          title: Value Form
      - name: period
        in: query
        required: false
        schema:
          type: string
          default: quarterly
          title: Period
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /equities/{ticker}/warehouse:
    get:
      tags:
      - Equities
      summary: Company Warehouse
      description: 'Every warehouse time series stored for a ticker, grouped by data schema.


        Ticker strings collide across exchanges, so listings are namespaced the

        way Yahoo Finance does it: a ".DE"-suffixed ticker serves the German

        listing only, and a bare ticker serves the US data only. When a bare

        ticker also matches a German company, the response carries a

        `german_listing` pointer to the ".DE" page instead of mixing two

        companies'' data on one page.


        Read-only against the DATA cluster. A schema that does not exist on the

        cluster yet comes back as an empty, `loaded: false` group instead of an

        error, so the view keeps working while a new company data source is still

        being built.'
      operationId: company_warehouse_equities__ticker__warehouse_get
      security:
      - HTTPBearer: []
      parameters:
      - name: ticker
        in: path
        required: true
        schema:
          type: string
          title: Ticker
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    WatchlistItem:
      properties:
        id:
          type: integer
          title: Id
        symbol:
          type: string
          title: Symbol
        company_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Company Name
        position:
          type: integer
          title: Position
        added_at:
          type: string
          format: date-time
          title: Added At
      type: object
      required:
      - id
      - symbol
      - position
      - added_at
      title: WatchlistItem
    WatchlistItemCreate:
      properties:
        symbol:
          type: string
          title: Symbol
        company_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Company Name
      type: object
      required:
      - symbol
      title: WatchlistItemCreate
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    WatchlistCreate:
      properties:
        name:
          type: string
          title: Name
      type: object
      required:
      - name
      title: WatchlistCreate
    Watchlist:
      properties:
        id:
          type: integer
          title: Id
        name:
          type: string
          title: Name
        position:
          type: integer
          title: Position
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        items:
          items:
            $ref: '#/components/schemas/WatchlistItem'
          type: array
          title: Items
      type: object
      required:
      - id
      - name
      - position
      - created_at
      - updated_at
      - items
      title: Watchlist
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WatchlistUpdate:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        position:
          anyOf:
          - type: integer
          - type: 'null'
          title: Position
      type: object
      title: WatchlistUpdate
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer