openapi: 3.1.0
info:
  title: BoliviaDB Product API
  version: 0.3.0-preview
  description: Fixture-backed preview of the planned BoliviaDB production API.
servers:
  - url: https://boliviadb.com/api
paths:
  /health:
    get:
      summary: Check public API health
      responses:
        "200": { description: Health response }
  /catalog:
    get:
      summary: Search customer-visible series
      parameters:
        - { in: query, name: q, schema: { type: string } }
        - { in: query, name: category, schema: { type: string } }
        - { in: query, name: source, schema: { type: string } }
        - { in: query, name: frequency, schema: { type: string } }
        - { in: query, name: availability, schema: { type: string, enum: [csv, api, vintages] } }
      responses:
        "200": { description: Catalog response }
  /series/{id}:
    get:
      summary: Get bilingual series metadata
      parameters:
        - { in: path, name: id, required: true, schema: { type: string } }
      responses:
        "200": { description: Series metadata }
        "404": { description: Not found }
  /series/{id}/observations:
    get:
      summary: Get observations
      parameters:
        - { in: path, name: id, required: true, schema: { type: string } }
        - { in: query, name: from, schema: { type: string, format: date } }
        - { in: query, name: to, schema: { type: string, format: date } }
        - { in: query, name: vintage, schema: { type: string, format: date } }
        - { in: query, name: limit, schema: { type: integer, minimum: 1, maximum: 10000 } }
      responses:
        "200": { description: Observation list }
        "404": { description: Not found }
  /series/{id}/vintages:
    get:
      summary: List available vintages
      parameters:
        - { in: path, name: id, required: true, schema: { type: string } }
      responses:
        "200": { description: Vintage list }
        "404": { description: Not found }
  /sources:
    get:
      summary: List source registry entries
      responses:
        "200": { description: Source list }
  /coverage:
    get:
      summary: List coverage roadmap entries
      responses:
        "200": { description: Coverage list }
  /calendar:
    get:
      summary: List illustrative release-calendar events
      parameters:
        - { in: query, name: source, schema: { type: string } }
        - { in: query, name: topic, schema: { type: string } }
        - { in: query, name: status, schema: { type: string, enum: [expected, released, delayed, revised] } }
      responses:
        "200": { description: Release-calendar response }