Aard Status API

openapi: 3.2.0
info:
  title: Aard REST Status API
  version: 1.0.0
  summary: Official economic and statistical data from 170+ publishers, resolved from natural language over plain HTTP.
  description: 'Four tools — `discover`, `inspect`, `ask`, `build_url` — each a `POST /v1/{tool}` taking one flat JSON object of arguments and returning the same output the MCP tool of that name produces. The tools return catalogue metadata and exact publisher requests, never observations: execute a returned plan client-side and query the parsed file locally.


    Authenticate with an API key minted at https://aard.ai/account/keys, sent as `Authorization: Bearer aard_live_…`. MCP OAuth tokens are not accepted here. Keys are bound to the account''s plan: its tool entitlements and monthly call cap (https://aard.ai/pricing). A call is charged only when the origin answers with a result — a 4xx, 429 or 502 is refunded rather than charged. The API is server-to-server: `/v1/*` sends no CORS headers, so a browser-hosted client cannot call it directly.


    Every `/v1/{tool}` response carries `X-Aard-Request-Id`. Every error is `{"ok": false, "error": ""[, "detail": "…"]}`; a 400 for an unknown or missing parameter name lists every accepted name in `detail`, so one round trip is enough to correct a call.


    Request schemas are transcribed from the origin''s validator (gsdmx2 0cee9034, 2026-09-17); the origin''s own contract test re-checks this document against that validator. The MCP surface at https://api.aard.ai/mcp carries six further tools, including bounded server-side dataset retrieval; see https://aard.ai/mcp.'
  termsOfService: https://aard.ai/terms
  contact:
    name: Aard
    url: https://aard.ai/contact
    email: hello@aard.ai
  license:
    name: Aard Terms of Service
    url: https://aard.ai/terms
servers:
- url: https://api.aard.ai
  description: Production gateway
security:
- apiKey: []
tags:
- name: Status
  description: Unauthenticated status endpoints.
paths:
  /v1/_health:
    get:
      operationId: health
      tags:
      - Status
      summary: Gateway health
      description: Public liveness check for the api.aard.ai gateway. Returns 200 and a stable body regardless of credentials; it does not exercise the origin.
      security: []
      responses:
        '200':
          description: The gateway is up.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
components:
  schemas:
    Health:
      type: object
      required:
      - ok
      - build
      properties:
        ok:
          const: true
        build:
          type:
          - string
          - 'null'
          description: The gateway build identifier, when the deploy carries one.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: aard_live_<key>
      description: An Aard API key from https://aard.ai/account/keys. Shown once on creation; revocable there.
externalDocs:
  description: Aard for agents and developers
  url: https://aard.ai/mcp
x-aard-source:
  repository: gsdmx2
  commit: 0cee9034
  paths:
  - src/gsdmx2/mcp/rest.py
  - docs/rest_api_v1.md
  transcribed: '2026-09-17'