Alphanume Ticker Classification API

openapi: 3.2.0
info:
  contact:
    url: https://alphanume.com
  description: 'Point-in-time, survivorship-aware datasets for US equities and options research. Every response is JSON: {"count": N, "data": [...]} (paginated endpoints add has_more and next_cursor). Dates are always YYYY-MM-DD. Access: every dataset requires an Alphanume Pro API key (the Free plan is retired as of September 6, 2026). A 403 error with code PRO_SUBSCRIPTION_REQUIRED or DATE_RANGE_RESTRICTED means the key''s plan does not cover the request -- it does not mean the data is missing. Authentication: send your API key in the X-API-Key header (or Authorization: Bearer). Rate limit: 600 requests/minute. Keys come with a Pro subscription at https://alphanume.com/pricing. The same datasets are available as MCP tools at https://mcp.alphanume.com/mcp.'
  title: Alphanume Ticker Classification API
  version: 1.1.0
servers:
- url: https://api.alphanume.com
security:
- ApiKeyHeader: []
- BearerKey: []
tags:
- name: Ticker Classification
paths:
  /v1/ticker-classification:
    get:
      description: 'Ticker sector/industry classification: maps every covered US ticker into

        Alphanume''s own 11-sector / 25-industry scheme (derived from SIC codes, but

        normalized into groups actually useful for trading -- e.g. ''semiconductors'' and

        ''software'' are separate industries under ''technology''). One row per ticker:

        ticker, alphanume_sector, alphanume_industry.


        Use it to group any other Alphanume dataset by sector, build sector-neutral

        baskets, or pull all names in one industry. Look up one `ticker`, or filter by

        `sector`/`industry` to enumerate a group. No date dimension and no tier

        restriction -- the mapping is current-state.'
      operationId: get_ticker_classification
      parameters:
      - description: Ticker symbol filter, e.g. 'AAPL'. Case-insensitive.
        in: query
        name: ticker
        required: false
        schema:
          type: string
      - description: Filter to one Alphanume sector.
        in: query
        name: sector
        required: false
        schema:
          enum:
          - essential_goods
          - raw_materials
          - energy_resources
          - consumer_cyclical
          - industrial_transport
          - communications_media
          - healthcare
          - technology
          - utilities_infrastructure
          - finance
          - real_assets
          type: string
      - description: Filter to one Alphanume industry.
        in: query
        name: industry
        required: false
        schema:
          enum:
          - food_beverage
          - basic_materials
          - energy_production
          - durables_apparel
          - industrial_equipment
          - business_services
          - media_content
          - pharma_biotech
          - household_products
          - automotive
          - hardware_devices
          - semiconductors
          - healthcare_services
          - transport_logistics
          - telecom
          - utilities
          - retail_cyclical
          - retail_staples
          - consumer_services
          - banking
          - financial_services
          - insurance
          - real_estate_development
          - reits
          - software
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          description: Matching rows.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      summary: 'Ticker sector/industry classification: maps every covered US ticker into'
      tags:
      - Ticker Classification
components:
  responses:
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: 'PRO_SUBSCRIPTION_REQUIRED: the key''s plan does not include API access; every endpoint requires an active Pro subscription. DATE_RANGE_RESTRICTED: a legacy free-tier key asked for dates outside its window. In both cases the data is not missing.'
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Missing or unrecognized API key.
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Invalid or conflicting query parameters.
    RateLimited:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Rate limit exceeded (600/min); the body carries retry_after_seconds.
  schemas:
    Envelope:
      properties:
        count:
          type: integer
        data:
          items:
            type: object
          type: array
      required:
      - count
      - data
      type: object
    Error:
      additionalProperties: true
      properties:
        error: {}
      type: object
  securitySchemes:
    ApiKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey
    BearerKey:
      scheme: bearer
      type: http
externalDocs:
  description: MCP server exposing these datasets as tools (OAuth or X-API-Key).
  url: https://mcp.alphanume.com/mcp