API Overview

Athena exposes a broad API grouped by responsibility.

Gateway + Query

• /gateway/fetch, /gateway/insert, /gateway/update, /gateway/delete
• /gateway/query, /gateway/sql, /query/sql, /query/count
• /gateway/rpc, /rpc/{function_name}
• /rest/v1/{table} compatibility routes

/gateway/fetch supports both the legacy columns contract and the PostgreSQL-backed structured-select contract documented in Gateway Structured Select.

Pipelines + Deferred Execution

• /pipelines, /pipelines/simulate, /pipelines/templates
• /gateway/deferred/{request_id}, /gateway/deferred/{request_id}/requeue

Schema + Introspection

• /schema/tables, /schema/columns, /schema/migrations
• /schema/clients, /clients

Admin + Operations

• /admin/clients*, /admin/api-keys*, /admin/backups*
• /admin/provision*, /admin/public-routes*
• /admin/tenant-hostnames/{tenant}
• /admin/webhooks*, /admin/admission-events
• /admin/vacuum-health*, /admin/clients/{client_name}/table-row-estimates, optimization and stats routes

Storage + Public Access

• /storage/objects*, /storage/objects/head
• /storage/buckets/list, /storage/buckets/create, /storage/buckets/delete, /storage/buckets/cors*
• /public/{route_key}/{op}
• wildcard host resolution through tenant.v3.athena-cluster.com when an active public_gateway_routes row exists

Search + Typesense Sync

• /typesense/backends/test, /typesense/collections/list
• /typesense/sync-jobs/{job_id}/run, /typesense/search

Optimization + Admission

• /admin/clients/{client_name}/query-optimizations*
• /admin/clients/{client_name}/table-row-estimates
• /admin/vacuum-health*
• /admin/admission-events

Management DDL Surface

• /management/tables*, /management/indexes*
• /management/extensions/install
• /management/functions
• /management/capabilities

Observability + Contracts

• /health/cluster, /metrics, /router/registry
• /openapi.yaml, /openapi-wss.yaml, /wss/info

Security and rate limits

• Security, auth ordering, and rate limits — storage auth before JSON, protected schema/registry/OpenAPI, raw SQL rights, backup admin, inbound/outbound rate limits, stats typing, and ops checklist.
• Gateway API Keys — the full runtime key model: creation, client binding, rights, IP policy, virgin lock-in, and fail modes.
• Tenant Wildcard Hostnames — the dedicated runbook for PUT /admin/tenant-hostnames/{tenant}, wildcard host routing, and PostgreSQL public-host metadata

Required Header Pattern

For most scoped calls:

X-Athena-Client: <logical-client-name>

For PostgreSQL gateway routes and PostgreSQL SQL driver calls, you can also route directly with:

x-pg-uri: postgres://<user>:<password>@<host>:<port>/<db>

(x-athena-jdbc-url and x-jdbc-url remain supported for compatibility.)

Direct PostgreSQL URI mode

Direct URI mode is scoped and intentional:

• Eligible routes: PostgreSQL gateway routes and PostgreSQL-driver calls for /query/sql and /gateway/sql
• Keyless bypass is only possible when the URI includes both username and password
• Non-PostgreSQL drivers still require standard auth

See Direct PostgreSQL Routing (x-pg-uri) for the full decision matrix and examples.

For protected routes outside this scope, include API key or admin key headers according to the rights model.

For full route-level coverage, use Reference -> Athena API Reference.