openapi: 3.0.3
info:
  title: CMS Open Payments Datastore Query API
  description: 'The CMS Open Payments public data API serves the federal transparency program that publishes payments and transfers of value from drug and medical device manufacturers and group purchasing organizations (GPOs) to physicians, non-physician practitioners, and teaching hospitals.


    The site at openpaymentsdata.cms.gov is a DKAN open data catalog. All read access is free and requires no authentication or API key. Data is organized as datasets (one per program year and payment category: General, Research, and Ownership and Investment), each backed by a datastore that can be queried with a structured query object, with SQL, or downloaded as CSV or JSON.


    This document models the public read surface only: the metastore catalog and search, the datastore structured query endpoints, the SQL query endpoint, and downloads. The DKAN write and moderation endpoints require Basic Authentication and are for CMS data publishers, not public consumers; they are out of scope here.'
  version: '1.0'
  contact:
    name: CMS Open Payments
    url: https://openpaymentsdata.cms.gov/about/api
  license:
    name: U.S. Government Work / Public Domain
    url: https://www.usa.gov/government-works
servers:
- url: https://openpaymentsdata.cms.gov/api/1
  description: CMS Open Payments public data API (DKAN)
tags:
- name: Datastore Query
  description: Structured query over a dataset distribution.
paths:
  /datastore/query/{datasetId}/{index}:
    get:
      operationId: queryDatastoreByDatasetGet
      tags:
      - Datastore Query
      summary: Query a dataset distribution (GET)
      description: Query the rows of a dataset's distribution by dataset id and distribution index (usually 0). Filtering, column selection, sorting, and pagination are expressed as query-string parameters. No authentication required.
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
        description: The dataset UUID.
      - name: index
        in: path
        required: true
        schema:
          type: integer
          default: 0
        description: The zero-based distribution index within the dataset.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 500
        description: Maximum number of rows to return.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
        description: Number of rows to skip for pagination.
      - name: conditions
        in: query
        required: false
        schema:
          type: string
        description: Filter conditions (property, value, operator).
      - name: properties
        in: query
        required: false
        schema:
          type: string
        description: Subset of columns to return.
      responses:
        '200':
          description: A page of matching rows plus row count, schema, and echoed query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
    post:
      operationId: queryDatastoreByDatasetPost
      tags:
      - Datastore Query
      summary: Query a dataset distribution (POST)
      description: Query the rows of a dataset's distribution by dataset id and distribution index using a structured JSON query body. Preferred for complex filters.
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
        description: The dataset UUID.
      - name: index
        in: path
        required: true
        schema:
          type: integer
          default: 0
        description: The zero-based distribution index within the dataset.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Query'
      responses:
        '200':
          description: A page of matching rows plus row count, schema, and echoed query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
  /datastore/query/{distributionId}:
    post:
      operationId: queryDatastoreByDistribution
      tags:
      - Datastore Query
      summary: Query a distribution directly
      description: Query a datastore resource directly by its distribution identifier (resolved from dataset metadata with show-reference-ids). The same query body can join across multiple distributions.
      parameters:
      - name: distributionId
        in: path
        required: true
        schema:
          type: string
        description: The distribution (datastore resource) identifier.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Query'
      responses:
        '200':
          description: A page of matching rows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
components:
  schemas:
    Query:
      type: object
      description: A structured datastore query.
      properties:
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/Condition'
        properties:
          type: array
          items:
            type: string
          description: Columns to return; omit for all columns.
        sorts:
          type: array
          items:
            type: object
            properties:
              property:
                type: string
              order:
                type: string
                enum:
                - asc
                - desc
        limit:
          type: integer
          default: 500
        offset:
          type: integer
          default: 0
    Condition:
      type: object
      properties:
        property:
          type: string
          description: Column name to filter on.
        value:
          type: string
          description: Value to compare against.
        operator:
          type: string
          description: Comparison operator (=, <>, >, <, >=, <=, like, in, between).
    QueryResult:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
          description: The matching rows.
        count:
          type: integer
          description: Total number of rows matching the query.
        schema:
          type: object
          description: Column schema for the queried resource.
        query:
          type: object
          description: The query as interpreted by the server.