openapi: 3.2.0
info:
  title: Delphi Epidata Meta API
  version: 4.1.44
  description: 'Public, anonymously accessible HTTP/JSON API operated by the Delphi research group at Carnegie Mellon University, serving real-time and historical epidemiological surveillance data. Delphi is a CMU research group (Machine Learning Department / Herbert A. Simon building, delphi.cmu.edu) and a former CDC Center of Excellence for Influenza Forecasting. The API is a single-host, query-parameter-driven surface: every endpoint is a GET under /epidata/, every response is a JSON envelope of {epidata, result, message}, and `result` carries Delphi''s own status convention (1 = success, -2 = no results, -1 = bad request) rather than relying on the HTTP status code alone. CMU publishes no OpenAPI, GraphQL schema or machine-readable contract for this API; this document was derived from live probes and from the prose documentation at cmu-delphi.github.io/delphi-epidata.'
  termsOfService: https://cmu-delphi.github.io/delphi-epidata/
  contact:
    name: Carnegie Mellon University — Delphi Research Group
    url: https://delphi.cmu.edu/
  license:
    name: See Delphi Epidata data-source licensing
    url: https://cmu-delphi.github.io/delphi-epidata/api/covidcast_licensing.html
  x-operator: institution
  x-operator-evidence: 'servers[] api.delphi.cmu.edu is a host under Carnegie Mellon University''s own registrable domain, cmu.edu. The API''s landing page at https://api.delphi.cmu.edu/epidata/ titles itself "DELPHI Epidata API" and links to github.com/cmu-delphi/delphi-epidata; the cmu-delphi GitHub organization is named "Delphi" with blog https://delphi.cmu.edu/. No vendor host, vendor contact or vendor terms appear anywhere on the surface. Probed 2026-08-19: /epidata/version 200 application/json {"version":"4.1.44"}; /epidata/covidcast_meta/ 200; /epidata/fluview/?regions=nat&epiweeks=202001 200; /epidata/covidcast/ with a full parameter set 200; /epidata/delphi/?system=ec&epiweek=201501 200.'
  x-provenance:
    generated: '2026-08-19'
    method: derived
    source: Live probes of https://api.delphi.cmu.edu/epidata/ on 2026-08-19 (five endpoints, real payloads captured into examples/), reconciled against the prose documentation at https://cmu-delphi.github.io/delphi-epidata/ and https://cmu-delphi.github.io/delphi-epidata/api/covidcast.html.
    authorship: Written by API Evangelist, not published by Carnegie Mellon University. CMU ships no machine-readable contract for this API — /epidata/openapi.json, /epidata/openapi.yaml, /epidata/openapi and /epidata/swagger.json all returned 404 on 2026-08-19, and no openapi.yaml exists in the cmu-delphi/delphi-epidata repository.
    coverage: Five of the roughly forty Delphi Epidata endpoints are modelled here — the ones actually probed. The signal-source endpoints (nowcast, flusurv, dengue_nowcast, wiki, ght, quidel, sensors, nidss_*, ecdc_ili, kcdc_ili, paho_dengue, norostat and the rest) share the same envelope and parameter idiom but were not individually probed and are deliberately absent rather than assumed.
servers:
- url: https://api.delphi.cmu.edu/epidata
  description: Production — Delphi Epidata API, operated by Carnegie Mellon University
tags:
- name: meta
  description: Service metadata and version.
paths:
  /version:
    get:
      tags:
      - meta
      operationId: getVersion
      summary: Get the running Epidata API version
      description: Returns the deployed version of the Delphi Epidata service as a bare JSON object. This is the only endpoint that does NOT use the {epidata, result, message} envelope.
      responses:
        '200':
          description: Version of the running service.
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    example: 4.1.44
              example:
                version: 4.1.44
  /covidcast_meta/:
    get:
      tags:
      - meta
      operationId: getCovidcastMeta
      summary: List every available COVIDcast signal and its coverage
      description: Returns one record per (data_source, signal, time_type, geo_type) combination available through the COVIDcast endpoint, with the date range, number of locations and summary statistics for each. This is the catalog a client reads before calling /covidcast/.
      responses:
        '200':
          description: Signal catalog.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpidataEnvelope'
components:
  schemas:
    EpidataEnvelope:
      type: object
      description: The response envelope every Delphi Epidata endpoint except /version uses. Note that errors are returned with HTTP 200 and signalled in `result` — a client keying only on the HTTP status will read a failed request as a success.
      required:
      - epidata
      - result
      - message
      properties:
        epidata:
          type: array
          description: The result rows; shape varies by endpoint. Empty on error or no-match.
          items:
            type: object
            additionalProperties: true
        result:
          type: integer
          description: Delphi status code. 1 = success, -2 = no results matched, -1 = bad or missing parameters. Not an HTTP status.
          enum:
          - 1
          - -1
          - -2
        message:
          type: string
          description: '`success`, `no results`, or a human-readable parameter error.'
          example: success