openapi: 3.0.3
info:
  title: SEC EDGAR Data Company Concept Search API
  description: 'The EDGAR Data API at data.sec.gov provides RESTful access to public company financial filings, XBRL structured financial data, and company metadata without requiring authentication or API keys. The API delivers JSON-formatted responses covering company submissions (filing history), XBRL financial facts across all reporting periods, single XBRL concept values over time, and cross-company comparative frames for US-GAAP and IFRS taxonomies.

    '
  version: 1.0.0
  contact:
    name: SEC EDGAR Help
    url: https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany
  license:
    name: Public Domain
    url: https://www.sec.gov/privacy.htm
  termsOfService: https://www.sec.gov/privacy.htm
servers:
- url: https://data.sec.gov
  description: SEC EDGAR Data API
tags:
- name: Search
  description: Full-text search across EDGAR filing documents
paths:
  /LATEST/search-index/efts:
    get:
      operationId: searchFilings
      summary: Search EDGAR filings by full text
      description: 'Searches the full text of EDGAR filings using Elasticsearch-backed indexing. Supports keyword queries, boolean operators, phrase matching, and field-specific filters. Results include filing metadata and direct links to matching documents. Rate limited to 10 requests per second.

        '
      tags:
      - Search
      parameters:
      - name: q
        in: query
        required: false
        description: 'Full-text search query. Supports phrase matching ("exact phrase"), boolean operators (AND, OR, NOT), and field-specific searches (e.g., entity_name:"Apple Inc"). Leave empty to browse all filings.

          '
        schema:
          type: string
          example: revenue recognition
      - name: dateRange
        in: query
        required: false
        description: 'Date range filter. Use "custom" to specify startdt and enddt, or "30d", "1y", "5y" for relative ranges.

          '
        schema:
          type: string
          enum:
          - custom
          - 30d
          - 1y
          - 5y
          example: custom
      - name: startdt
        in: query
        required: false
        description: 'Start date for custom date range filter (YYYY-MM-DD format). Only used when dateRange is "custom".

          '
        schema:
          type: string
          format: date
          example: '2023-01-01'
      - name: enddt
        in: query
        required: false
        description: 'End date for custom date range filter (YYYY-MM-DD format). Only used when dateRange is "custom".

          '
        schema:
          type: string
          format: date
          example: '2023-12-31'
      - name: forms
        in: query
        required: false
        description: 'Comma-separated list of form types to filter results. Example: 10-K,10-Q,8-K

          '
        schema:
          type: string
          example: 10-K,10-Q
      - name: entity
        in: query
        required: false
        description: 'Filter by entity name. Partial matches supported.

          '
        schema:
          type: string
          example: Apple Inc
      - name: ticker
        in: query
        required: false
        description: 'Filter by stock ticker symbol.

          '
        schema:
          type: string
          example: AAPL
      - name: _source
        in: query
        required: false
        description: 'Comma-separated list of fields to return in the response. Default returns all fields.

          '
        schema:
          type: string
      - name: from
        in: query
        required: false
        description: 'Starting offset for pagination (zero-based).

          '
        schema:
          type: integer
          minimum: 0
          default: 0
          example: 0
      - name: size
        in: query
        required: false
        description: 'Number of results to return per page. Maximum is 10 per request for full-text results.

          '
        schema:
          type: integer
          minimum: 1
          maximum: 10
          default: 10
          example: 10
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid query parameters
        '429':
          description: Rate limit exceeded (10 requests per second)
components:
  schemas:
    FilingDocument:
      type: object
      description: Metadata for an EDGAR filing document
      properties:
        period_of_report:
          type: string
          format: date
          description: Period of report date
          example: '2023-09-30'
        entity_name:
          type: string
          description: Entity name
          example: Apple Inc.
        file_num:
          type: string
          description: SEC file number
          example: 001-36743
        film_num:
          type: string
          description: Film number
        form_type:
          type: string
          description: Form type
          example: 10-K
        biz_location:
          type: string
          description: Business location (state/country)
          example: CA
        inc_states:
          type: string
          description: State of incorporation
          example: CA
        file_date:
          type: string
          format: date
          description: Filing date
          example: '2023-11-03'
        accession_no:
          type: string
          description: EDGAR accession number
          example: 0000320193-23-000106
        category:
          type: string
          description: Filing category
          example: form-type
        display_date_filed:
          type: string
          description: Human-readable filing date
          example: '2023-11-03'
        ticker:
          type: array
          items:
            type: string
          description: Ticker symbols
          example:
          - AAPL
        xsl:
          type: string
          description: XSL stylesheet filename
        id:
          type: string
          description: Document identifier
        inline_xbrl:
          type: boolean
          description: Whether the filing uses inline XBRL
        file_id:
          type: string
          description: File identifier
    SearchResponse:
      type: object
      description: Full-text search results from EDGAR
      properties:
        hits:
          type: object
          description: Search hit metadata and results
          properties:
            total:
              type: object
              description: Total hit count
              properties:
                value:
                  type: integer
                  description: Number of matching documents
                  example: 1234
                relation:
                  type: string
                  description: Whether total is exact or approximate
                  enum:
                  - eq
                  - gte
                  example: eq
            hits:
              type: array
              description: Array of matching filing documents
              items:
                $ref: '#/components/schemas/SearchHit'
    SearchHit:
      type: object
      description: A single filing document matching the search query
      properties:
        _id:
          type: string
          description: Unique document identifier
        _score:
          type: number
          description: Elasticsearch relevance score
        _source:
          $ref: '#/components/schemas/FilingDocument'