FactIQ Catalog API

openapi: 3.2.0
info:
  title: FactIQ Catalog 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: Catalog
paths:
  /catalog/series_counts:
    get:
      tags:
      - Catalog
      summary: Get Series Counts
      description: 'Latest series count per schema, plus the grand total.


        Only publicly visible schemas are counted, so this endpoint and

        `/catalog/schemas` describe the same set of sources — a hidden or

        admin-only schema is not named here either.


        Response: {"counts": {schema: count, ...}, "total": int,

        "counted_at": ISO timestamp of the newest snapshot | null}'
      operationId: get_series_counts_catalog_series_counts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /catalog/schemas:
    get:
      tags:
      - Catalog
      summary: Get Schemas
      description: 'Every publicly visible schema with its identity, summary and counts.


        Response: {"schemas": [{schema, organization, country, acronym, summary,

        dataset_count, series_count, has_series_tables}],

        "tables": TABLE_REFERENCE, "example_sql": str,

        "counted_at": str | null}


        `dataset_count` is the number of datasets loaded in the database when that

        has been computed (see `_db_dataset_counts`), else the number described in

        the catalog metadata; any schema still on the metadata figure is queued

        for a background warm.'
      operationId: get_schemas_catalog_schemas_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /catalog/search:
    get:
      tags:
      - Catalog
      summary: Catalog Search
      description: Search public datasets and companies with verified FactIQ holdings.
      operationId: catalog_search_catalog_search_get
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 200
          title: Q
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 20
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catalog/datasets/{schema}:
    get:
      tags:
      - Catalog
      summary: Get Datasets
      description: 'Datasets loaded in one schema: [{dataset_code, title, topic,

        series_count}] sorted by title.


        Described-but-unloaded datasets are dropped; loaded-but-undescribed ones

        are included with their code as the title. If the database cannot be

        reached the described list is returned without counts.'
      operationId: get_datasets_catalog_datasets__schema__get
      parameters:
      - name: schema
        in: path
        required: true
        schema:
          type: string
          title: Schema
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catalog/datasets/{schema}/{dataset_code}:
    get:
      tags:
      - Catalog
      summary: Get Dataset Detail
      description: 'Full detail for one dataset: topic, methodology, live dimensions and

        example series. Cached for six hours — the dimension scan can be slow on

        the largest schemas.'
      operationId: get_dataset_detail_catalog_datasets__schema___dataset_code__get
      parameters:
      - name: schema
        in: path
        required: true
        schema:
          type: string
          title: Schema
      - name: dataset_code
        in: path
        required: true
        schema:
          type: string
          title: Dataset Code
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catalog/sample/{schema}/{series_id}:
    get:
      tags:
      - Catalog
      summary: Get Series Sample
      description: 'A series'' catalog row plus its most recent rows.


        Response: {"series": {...series columns...}, "columns": [...],

        "rows": [[...], ...], "total_rows": int}'
      operationId: get_series_sample_catalog_sample__schema___series_id__get
      parameters:
      - name: schema
        in: path
        required: true
        schema:
          type: string
          title: Schema
      - name: series_id
        in: path
        required: true
        schema:
          type: string
          title: Series Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catalog/series/{schema}:
    get:
      tags:
      - Catalog
      summary: List Series
      description: 'The series of one dataset, in pages.


        Response: {"schema", "dataset_code", "query", "dimension_type",

        "dimension_code", "series": [{series_id, title, units, frequency,

        seasonally_adjusted, state, county_or_metro_area, begin_time, end_time,

        data_type}], "offset", "limit", "has_more", "total", "order", "ranking",

        "error"}.


        ``total`` is the dataset''s series count when nothing is filtered, the

        number of matches when a filter is set and counting them finished in

        time, else null. ``error`` is set, with an empty list, when the

        statement exceeded its time limit on a very large dataset.


        ``order=storage`` (the default) pages through the matches in series_id

        order. ``order=headline`` pages through the first 480 matches in that

        order ranked the way the dataset''s example series are picked: the series

        that report every period up to the dataset''s latest date come first, one

        per group of near-identical titles before any group''s second. When the

        dataset has a hand-picked list of headline series (``headline_series`` in

        dataset_catalog) and nothing is filtered, those come first in their

        curated order and the ranked series follow. ``ranking`` says what the

        page is: ``curated`` when it starts with the hand-picked list, ``ranked``

        when every match was scored, ``sampled`` when only the first 480 of more

        matches were, ``storage`` when the order is storage order (asked for, or

        the ranking exceeded its time limit).'
      operationId: list_series_catalog_series__schema__get
      parameters:
      - name: schema
        in: path
        required: true
        schema:
          type: string
          title: Schema
      - name: dataset
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 64
          title: Dataset
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Q
      - name: dimension_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Dimension Type
      - name: dimension_code
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Dimension Code
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          maximum: 5000
          minimum: 0
          default: 0
          title: Offset
      - name: order
        in: query
        required: false
        schema:
          type: string
          pattern: ^(storage|headline)$
          default: storage
          title: Order
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catalog/facets/{schema}/{dataset_code}:
    get:
      tags:
      - Catalog
      summary: Get Dataset Facets
      description: 'Frequencies, date range and the common dimension values of a dataset.


        Response: {"schema", "dataset_code", "summary": {frequencies: [{frequency,

        series_count}], begin_time, end_time, series_count, sampled?,

        sample_size?, error?}, "facets": [{dimension_type, distinct_values,

        sampled, values: [{code, name, series_count}]}], "error"?}.


        Cached for six hours. On the largest datasets the exact grouping exceeds

        the time limit and the values come from a sample of the series, marked

        ``sampled``; a dataset without series answers 404.


        With ``summary_only=true`` the dimension values are not computed and

        ``facets`` is empty. Grouping the dimension rows is the slow part on the

        largest datasets (up to 37 million rows), so a caller that only shows the

        summary should ask for it alone. A full cached response answers such a

        request too; a summary-only response is cached under its own key and is

        never served to a request that wants the values.'
      operationId: get_dataset_facets_catalog_facets__schema___dataset_code__get
      parameters:
      - name: schema
        in: path
        required: true
        schema:
          type: string
          title: Schema
      - name: dataset_code
        in: path
        required: true
        schema:
          type: string
          title: Dataset Code
      - name: summary_only
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Summary Only
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catalog/sparklines/{schema}:
    get:
      tags:
      - Catalog
      summary: Get Sparklines
      description: 'The last sixty observations of up to twenty-four series of a schema.


        ``ids`` is repeated (``?ids=A&ids=B``); duplicates are dropped and the

        order is kept. Response: {"schema", "series": {series_id: {title, units,

        frequency, data_type, points: [[date, value], ...] oldest first,

        first_time, latest_time, latest_value}}, "missing": [ids not in the

        schema], "error"?}. A tabular series has no points. Each series is cached

        for an hour under the schema''s series generation, so a load of new data

        replaces it at once.'
      operationId: get_sparklines_catalog_sparklines__schema__get
      parameters:
      - name: schema
        in: path
        required: true
        schema:
          type: string
          title: Schema
      - name: ids
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
          title: Ids
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catalog/related/{schema}/{series_id}:
    get:
      tags:
      - Catalog
      summary: Get Related Series
      description: 'The eight series of the same dataset most like one series.


        The candidates are the 24 series on each side of it in series_id order

        (ids of one dataset are built from the same code parts, so neighbours

        share area, measure or product). Each is scored on shared frequency,

        state, county and title words; the best eight are returned as listing

        rows. Response: {"schema", "series_id", "dataset_code", "dataset_title",

        "related": [rows], "error"?}. 404 when the series does not exist. Cached

        for six hours.'
      operationId: get_related_series_catalog_related__schema___series_id__get
      parameters:
      - name: schema
        in: path
        required: true
        schema:
          type: string
          title: Schema
      - name: series_id
        in: path
        required: true
        schema:
          type: string
          title: Series Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catalog/companies:
    get:
      tags:
      - Catalog
      summary: List Markets
      description: 'Every filing market with its company and report counts.


        Response: {"markets": [{key, slug, country_code, country, regulator,

        company_count, filing_count, first_period, last_period,

        companies_with_calls, companies_with_media}],

        "basis": str, "counted_at": ISO timestamp}


        Markets are in a fixed order (United States first); a market with no

        company is listed with zero counts.'
      operationId: list_markets_catalog_companies_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /catalog/companies/{slug}:
    get:
      tags:
      - Catalog
      summary: List Market Companies
      description: 'Every company of one market that has a filing or an earnings call.


        Response: {"market": {...}, "companies": [{ticker, name, country_code,

        filing_count, first_period, last_period, transcript_count,

        appearance_count}], "basis": str, "counted_at": str}


        A company without a ticker in this market is left out, because its page

        could not be addressed; the count of such rows is logged.'
      operationId: list_market_companies_catalog_companies__slug__get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catalog/companies/{slug}/{ticker}:
    get:
      tags:
      - Catalog
      summary: Get Company
      description: 'Exactly what FactIQ holds for one company of one market.


        The ticker is resolved against the securities of that market, so the

        same company can be reached as ``united-states/TM`` and ``japan/7203.T``;

        both pages show every market''s reports. 404 when the market or ticker is

        unknown. Only counts, names, periods, source links and the filing-backed

        headline figures (``headline_figures``) are returned.'
      operationId: get_company_catalog_companies__slug___ticker__get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      - 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:
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer