openapi: 3.0.3
info:
  title: CMS Open Payments Datastore Query Metastore 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: Metastore
  description: DCAT-US dataset catalog and metadata.
paths:
  /metastore/schemas/dataset/items:
    get:
      operationId: listDatasets
      tags:
      - Metastore
      summary: List all datasets
      description: Returns the DCAT-US metadata for every Open Payments dataset (each program year of General, Research, and Ownership data). No authentication required.
      parameters:
      - name: page-size
        in: query
        required: false
        schema:
          type: integer
          default: 10
        description: Number of dataset items to return.
      - name: page
        in: query
        required: false
        schema:
          type: integer
        description: Page number for pagination.
      responses:
        '200':
          description: An array of dataset metadata objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dataset'
  /metastore/schemas/dataset/items/{datasetId}:
    get:
      operationId: getDataset
      tags:
      - Metastore
      summary: Get one dataset's metadata
      description: Returns the DCAT-US metadata for a single dataset. Pass show-reference-ids to resolve the distribution and datastore identifiers needed to query the data.
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
        description: The dataset UUID.
      - name: show-reference-ids
        in: query
        required: false
        schema:
          type: boolean
        description: When present, expands distribution reference identifiers.
      responses:
        '200':
          description: A dataset metadata object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Dataset:
      type: object
      description: DCAT-US dataset metadata.
      properties:
        title:
          type: string
        description:
          type: string
        accessLevel:
          type: string
        keyword:
          type: array
          items:
            type: string
        contactPoint:
          type: object
        distribution:
          type: array
          items:
            $ref: '#/components/schemas/Distribution'
    Distribution:
      type: object
      description: A downloadable / queryable resource within a dataset.
      properties:
        identifier:
          type: string
          description: The distribution (datastore resource) identifier.
        title:
          type: string
        format:
          type: string
        downloadURL:
          type: string
    Error:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
        timestamp:
          type: string
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'