openapi: "3.1.0"
info:
  title: UnGovr Open Data API
  version: "1.0"
  description: |
    Free, read-only access to 322,567+ government entities
    and 8,536+ California Grand Jury reports.
  contact:
    email: api@ungovr.org
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
  - url: https://data.ungovr.org/v1
paths:
  /entities/index.json:
    get:
      summary: List all countries with entity counts
      responses:
        "200":
          description: Country list with entity counts and navigation URLs
  /entities/{cc}.json:
    get:
      summary: Entities for one country
      parameters:
        - name: cc
          in: path
          required: true
          schema:
            type: string
            minLength: 2
            maxLength: 2
      responses:
        "200":
          description: Country entity slice
  /entities/{cc}/{state}.json:
    get:
      summary: Entities for one state/province
      parameters:
        - name: cc
          in: path
          required: true
          schema:
            type: string
        - name: state
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: State entity slice
  /entities/detail/{slug}.json:
    get:
      summary: Full entity detail
      parameters:
        - name: slug
          in: path
          required: true
          description: Entity slug with '/' replaced by '--' (e.g. 'us--ca--ventura')
          schema:
            type: string
      responses:
        "200":
          description: Entity detail record
  /entities/children/{slug}.json:
    get:
      summary: Child entities list
      parameters:
        - name: slug
          in: path
          required: true
          description: Entity slug with '/' replaced by '--' (e.g. 'us--ca')
          schema:
            type: string
      responses:
        "200":
          description: Children list with parent info
  /entities/boundaries/{slug}.geojson:
    get:
      summary: Geographic boundary (GeoJSON Feature)
      parameters:
        - name: slug
          in: path
          required: true
          description: Entity slug with '/' replaced by '--' (e.g. 'us--ca--ventura')
          schema:
            type: string
      responses:
        "200":
          description: GeoJSON Feature with boundary geometry
  /cgj/index.json:
    get:
      summary: All CGJ reports (lightweight index)
      responses:
        "200":
          description: Array of CGJ index records
  /cgj/counties.json:
    get:
      summary: County list with report counts
      responses:
        "200":
          description: Counties index
  /cgj/counties/{code}.json:
    get:
      summary: Reports for one county
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: County report list
  /cgj/reports/{id}.json:
    get:
      summary: Full CGJ report with findings
      security:
        - apiKey: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: CGJ report detail
        "401":
          description: API key required
        "429":
          description: Daily limit exceeded
  /meta/last-updated.json:
    get:
      summary: Build timestamp and record counts
      responses:
        "200":
          description: Last-updated metadata
  /meta/countries.json:
    get:
      summary: Country list with entity counts
      responses:
        "200":
          description: Countries metadata
  /request/service-types.json:
    get:
      summary: Service types for all supported countries
      responses:
        "200":
          description: Service types index with categories
  /request/service-types/{cc}.json:
    get:
      summary: Service types for one country
      parameters:
        - name: cc
          in: path
          required: true
          schema:
            type: string
            enum: [us, ie, gb]
      responses:
        "200":
          description: Country service types grouped by category
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key