openapi: 3.1.0
info:
  title: FINRA Developer Center API
  description: |-
    The FINRA (Financial Industry Regulatory Authority) Developer Center exposes
    a REST Query API for accessing market data, regulatory datasets, and related
    metadata. The Query API provides dataset metadata, partition information,
    record-level retrieval, and asynchronous query support across organized
    groups and named datasets.
  version: '1.0'
  contact:
    name: FINRA Developer Center
    url: https://developer.finra.org/
servers:
  - url: https://api.finra.org
    description: Production
  - url: https://api-int.qa.finra.org
    description: QA Test
x-generated-from: https://developer.finra.org/
x-generated-by: claude-crawl-2026-05-08
tags:
  - name: Datasets
    description: Dataset discovery and listing.
  - name: Metadata
    description: Field-level metadata for datasets.
  - name: Partitions
    description: Partition values for datasets.
  - name: Data
    description: Querying records from datasets.
  - name: Async
    description: Asynchronous query operations.
security:
  - bearerAuth: []
paths:
  /datasets:
    get:
      tags:
        - Datasets
      summary: List datasets
      description: Returns a comprehensive list of all Query API datasets.
      operationId: listDatasets
      responses:
        '200':
          description: List of datasets.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /metadata/group/{group}/name/{dataset}:
    get:
      tags:
        - Metadata
      summary: Get dataset metadata
      description: Returns dataset metadata, including the available fields.
      operationId: getDatasetMetadata
      parameters:
        - $ref: '#/components/parameters/GroupParam'
        - $ref: '#/components/parameters/DatasetParam'
      responses:
        '200':
          description: Dataset metadata.
          content:
            application/json:
              schema:
                type: object
        '404':
          $ref: '#/components/responses/NotFound'
  /partitions/group/{group}/name/{dataset}:
    get:
      tags:
        - Partitions
      summary: List dataset partitions
      description: Retrieves unique partition values for a dataset.
      operationId: listDatasetPartitions
      parameters:
        - $ref: '#/components/parameters/GroupParam'
        - $ref: '#/components/parameters/DatasetParam'
      responses:
        '200':
          description: Partition values.
          content:
            application/json:
              schema:
                type: object
        '404':
          $ref: '#/components/responses/NotFound'
  /data/group/{group}/name/{dataset}:
    get:
      tags:
        - Data
      summary: Query dataset (simple)
      description: Queries dataset records using optional limit and field selectors.
      operationId: queryDataset
      parameters:
        - $ref: '#/components/parameters/GroupParam'
        - $ref: '#/components/parameters/DatasetParam'
        - name: limit
          in: query
          required: false
          description: Maximum number of records to return.
          schema:
            type: integer
        - name: fields
          in: query
          required: false
          description: Comma-separated list of fields to return.
          schema:
            type: string
      responses:
        '200':
          description: Query results.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '400':
          $ref: '#/components/responses/BadRequest'
    post:
      tags:
        - Data
      summary: Query dataset (advanced)
      description: Submits an advanced query using filters in the request body.
      operationId: queryDatasetAdvanced
      parameters:
        - $ref: '#/components/parameters/GroupParam'
        - $ref: '#/components/parameters/DatasetParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Query results.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '400':
          $ref: '#/components/responses/BadRequest'
  /data/group/{group}/name/{dataset}/id/{id}:
    get:
      tags:
        - Data
      summary: Get dataset record by id
      description: Retrieves a single record from supported datasets by id.
      operationId: getDatasetRecordById
      parameters:
        - $ref: '#/components/parameters/GroupParam'
        - $ref: '#/components/parameters/DatasetParam'
        - name: id
          in: path
          required: true
          description: Record identifier.
          schema:
            type: string
      responses:
        '200':
          description: Record.
          content:
            application/json:
              schema:
                type: object
        '404':
          $ref: '#/components/responses/NotFound'
  /async-requests/group/{group}/name/{dataset}/{requestId}:
    get:
      tags:
        - Async
      summary: Get async request status
      description: Returns the status and result location for an asynchronous query request.
      operationId: getAsyncRequestStatus
      parameters:
        - $ref: '#/components/parameters/GroupParam'
        - $ref: '#/components/parameters/DatasetParam'
        - name: requestId
          in: path
          required: true
          description: Asynchronous request identifier.
          schema:
            type: string
      responses:
        '200':
          description: Async request status.
          content:
            application/json:
              schema:
                type: object
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer token issued by FINRA Identity Provider.
  parameters:
    GroupParam:
      name: group
      in: path
      required: true
      description: Dataset group identifier.
      schema:
        type: string
    DatasetParam:
      name: dataset
      in: path
      required: true
      description: Dataset name within the group.
      schema:
        type: string
  responses:
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            type: object
    Unauthorized:
      description: Missing or invalid authentication.
      content:
        application/json:
          schema:
            type: object
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            type: object