> ## Documentation Index
> Fetch the complete documentation index at: https://hfsaa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get dataset metadata

> Returns metadata about the directory dataset and API contract.



## OpenAPI

````yaml /openapi.yaml get /v1/dataset
openapi: 3.1.0
info:
  title: HFSAA Public API
  version: 1.2.2
  description: >
    API-key protected access to HFSAA-certified restaurants, meat markets, and
    dining halls.

    Every directory-data route in the `/v1` namespace requires an API key; there
    are no

    anonymous data endpoints. Public health and developer-onboarding routes are
    explicitly

    marked with `security: []` and do not expose directory data.

    Developers can request test access without creating an account. Test keys do
    not

    expire automatically, but they are restricted to the test environment and
    quota.

    Successful data responses may be cached privately for no more than one hour.
  contact:
    name: HFSAA
servers:
  - url: https://api.hfsaa.org
    description: Production
  - url: https://hfsaa-public-api-staging.idris-ocasio.workers.dev
    description: Test
security:
  - ApiKeyAuth: []
paths:
  /v1/dataset:
    get:
      tags:
        - Metadata
      summary: Get dataset metadata
      description: Returns metadata about the directory dataset and API contract.
      operationId: getDatasetMetadata
      responses:
        '200':
          description: Dataset metadata.
          headers:
            Cache-Control:
              $ref: '#/components/headers/DataCacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  headers:
    DataCacheControl:
      description: >-
        Private caching is permitted for at most one hour. Revalidate after
        expiry; shared caches must not store authenticated responses.
      schema:
        type: string
        example: private, max-age=3600, must-revalidate
  schemas:
    DatasetMetadata:
      type: object
      additionalProperties: false
      required:
        - api_version
        - dataset_version
        - generated_at
        - location_count
        - checksum
        - download_url
        - location_types
        - attribution
      properties:
        api_version:
          type: string
          example: v1
        dataset_version:
          type: string
          description: Opaque immutable version of the current dataset.
        generated_at:
          type: string
          format: date-time
          description: UTC time at which this snapshot was generated.
        location_count:
          type: integer
          minimum: 0
          description: Exact number of locations in this dataset version.
        checksum:
          $ref: '#/components/schemas/Checksum'
        download_url:
          type: string
          format: uri
          description: Version-specific URL for the exact artifact covered by checksum.
        location_types:
          type: array
          items:
            $ref: '#/components/schemas/LocationType'
        attribution:
          type: object
          additionalProperties: false
          required:
            - required
            - text
            - instructions
          properties:
            required:
              type: boolean
              example: true
            text:
              type: string
              example: HFSAA certification
            instructions:
              type: string
              example: >-
                When stating or implying that a location is certified or halal
                verified by HFSAA, identify HFSAA and provide reasonable access
                to the location's exact verification_url.
    Checksum:
      type: object
      additionalProperties: false
      required:
        - algorithm
        - value
      properties:
        algorithm:
          type: string
          enum:
            - sha256
        value:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: >-
            Lowercase hexadecimal SHA-256 checksum of the exact downloaded
            artifact bytes.
    LocationType:
      type: string
      enum:
        - restaurant
        - meat_market
        - dining_hall
    Error:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: invalid_parameter
            message:
              type: string
              example: limit must be between 1 and 100.
  responses:
    Unauthorized:
      description: The Bearer credential is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        The API key is recognized but has been revoked or is not permitted to
        access the resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: The API key's per-minute or monthly allowance was exceeded.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            example: 60
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: >-
        The service or an upstream dependency could not complete the request.
        Retry with exponential backoff and jitter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: The service is temporarily unavailable. Retry after the indicated delay.
      headers:
        Retry-After:
          description: Seconds to wait before retrying when known.
          schema:
            type: integer
            example: 60
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: hfsaa_test_... or hfsaa_live_...
      description: 'Use the API key as `Authorization: Bearer <api-key>`.'

````