openapi: 3.0.3
info:
  title: StockData Entities API
  description: StockData.org provides free real-time, intraday, and historical stock, forex, and cryptocurrency market data along with global financial news and sentiment analysis. The API delivers market data for US-listed stocks including OHLCV data, splits, dividends, and entity-level news sentiment from 5,000+ sources in 30+ languages. All endpoints require an api_token parameter.
  version: '1.0'
  contact:
    url: https://www.stockdata.org/
  termsOfService: https://www.stockdata.org/terms
servers:
- url: https://api.stockdata.org/v1
  description: Production Server
security:
- ApiToken: []
tags:
- name: Entities
  description: Entity search and metadata
paths:
  /entity/search:
    get:
      operationId: searchEntities
      summary: Search Entities
      description: Dynamic search for financial entities (stocks, ETFs, indices, crypto, currencies) with filtering by type, industry, exchange, and country.
      tags:
      - Entities
      parameters:
      - name: api_token
        in: query
        required: true
        schema:
          type: string
        description: Your API token from the StockData dashboard.
      - name: search
        in: query
        required: false
        schema:
          type: string
        description: Search query matching entity name or symbol.
      - name: symbols
        in: query
        required: false
        schema:
          type: string
        description: Filter by comma-separated ticker symbols.
      - name: exchanges
        in: query
        required: false
        schema:
          type: string
        description: Filter by exchange codes.
      - name: types
        in: query
        required: false
        schema:
          type: string
        description: Filter by entity type (equity, etf, index, etc.).
      - name: industries
        in: query
        required: false
        schema:
          type: string
        description: Filter by industry classification.
      - name: countries
        in: query
        required: false
        schema:
          type: string
        description: Filter by country code.
      responses:
        '200':
          description: Entity search results returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySearchResponse'
        '401':
          description: Invalid or missing API token.
  /entity/type/list:
    get:
      operationId: listEntityTypes
      summary: List Entity Types
      description: Returns all supported entity types including equity, index, ETF, mutual fund, currency, and cryptocurrency.
      tags:
      - Entities
      parameters:
      - name: api_token
        in: query
        required: true
        schema:
          type: string
        description: Your API token from the StockData dashboard.
      responses:
        '200':
          description: Entity types list returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TypeListResponse'
        '401':
          description: Invalid or missing API token.
  /entity/industry/list:
    get:
      operationId: listIndustries
      summary: List Industries
      description: Retrieve all supported industry classifications for entity filtering.
      tags:
      - Entities
      parameters:
      - name: api_token
        in: query
        required: true
        schema:
          type: string
        description: Your API token from the StockData dashboard.
      responses:
        '200':
          description: Industry list returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndustryListResponse'
        '401':
          description: Invalid or missing API token.
components:
  schemas:
    TypeListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: string
          description: List of supported entity type strings.
    Entity:
      type: object
      properties:
        symbol:
          type: string
          description: Entity ticker symbol.
        name:
          type: string
          description: Entity name.
        type:
          type: string
          description: Entity type (equity, etf, index, crypto, currency).
        industry:
          type: string
          description: Industry classification.
        exchange:
          type: string
          description: Exchange short code.
        exchange_long:
          type: string
          description: Exchange full name.
        mic_code:
          type: string
          description: Market identifier code.
        country:
          type: string
          description: Country code.
        currency:
          type: string
          description: Trading currency.
    Meta:
      type: object
      properties:
        found:
          type: integer
          description: Total number of records matching the query.
        returned:
          type: integer
          description: Number of records returned in this response.
        limit:
          type: integer
          description: Maximum records per page.
        page:
          type: integer
          description: Current page number.
    EntitySearchResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Entity'
    IndustryListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: string
          description: List of supported industry classification strings.
  securitySchemes:
    ApiToken:
      type: apiKey
      in: query
      name: api_token
      description: API token obtained from the StockData dashboard.