canonical: https://jentic.com/apis/hasura.io/hasura

# Hasura GraphQL Engine API

Jentic publishes the only available OpenAPI specification for Hasura GraphQL Engine API, keeping it validated and agent-ready. Hasura GraphQL Engine exposes instant GraphQL APIs over Postgres and other databases, with a metadata layer that lets you manage schemas, permissions, remote sources, and event triggers programmatically. The spec covers the core `/v1/graphql` query endpoint plus the `/v1/metadata` and `/v1/query` administrative endpoints used to configure the engine. Operators use it to script project bootstrapping, run migrations, and integrate Hasura into CI/CD pipelines without clicking through the console.

## For AI agents

Run GraphQL queries and mutations against Hasura-managed databases and apply metadata changes such as tracking tables, setting permissions, and managing remote schemas through a single admin endpoint.

## Scope

Does not handle authentication, file storage, or background job orchestration - use for GraphQL queries and Hasura metadata management only.

## Capabilities

- Execute GraphQL queries and mutations against tracked Postgres tables via the `/v1/graphql` endpoint
- Track tables, views, and relationships through metadata commands sent to `/v1/metadata`
- Apply role-based permissions and remote schema configurations without restarting the engine
- Run raw SQL and bulk metadata operations through the `/v2/query` endpoint for migrations
- Probe instance health and version with the /healthz and `/v1/version` checks before deploying changes
- Drive Hasura project bootstrapping and CI/CD migrations from scripted automation

## Use cases

### Programmatic Schema Management

Manage Hasura table tracking, relationships, and permissions from migration scripts instead of the console. Send metadata commands to `/v1/metadata` to track new tables, define foreign-key relationships, and apply role-based permissions whenever the underlying Postgres schema changes. This keeps Hasura configuration in version control and removes manual setup steps when promoting between staging and production.

Example prompt: Send a track_table metadata command to `/v1/metadata` for the public.orders table and confirm it appears in the resulting metadata export

### GraphQL Query Execution from Backend Services

Call `/v1/graphql` from server-side code or scheduled jobs to query and mutate data without writing SQL. Hasura compiles each GraphQL operation into a single optimized SQL query, applying the role and permission rules attached to the request. Backend workers, ETL jobs, and AI agents use this to read or update data through a typed contract instead of direct database access.

Example prompt: Execute a GraphQL mutation against `/v1/graphql` to insert a new order row and read back the generated id

### CI/CD Health Checks and Version Pinning

Wire /healthz and `/v1/version` into deployment pipelines to verify the Hasura instance is reachable and running the expected build before applying metadata changes. The version endpoint returns the running engine version so migrations can fail fast if the target environment is on an incompatible release. This reduces the chance of metadata drift between environments.

Example prompt: Call GET /healthz and GET `/v1/version`, verify a 200 response, and assert the version string starts with v2

### AI Agent Data Access via Jentic

Agents discover the Hasura GraphQL Engine API through Jentic by searching for an intent like running a GraphQL query, then load the schema for `/v1/graphql` and execute the call without ever seeing the admin secret. Jentic securely stores the X-Hasura-Admin-Secret header, scopes credentials per agent, and returns structured results that the agent can pass to downstream steps. This turns Hasura into a data tool that any toolkit can use safely.

Example prompt: Use Jentic search 'run a graphql query on hasura' to load `/v1/graphql` and execute a query for the latest 10 orders

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/graphql` | Run GraphQL queries and mutations |
| POST | `/v1/metadata` | Apply metadata commands such as track_table |
| POST | `/v1/query` | Run schema and data manipulation queries |
| POST | `/v2/query` | Run v2 raw SQL and bulk operations |
| GET | `/v1/version` | Return the running engine version |
| GET | `/healthz` | Probe instance health |

## Key resources

- **GraphQL** — Submit GraphQL queries, mutations, and subscriptions through `/v1/graphql`
- **Metadata** — Track tables, relationships, permissions, and remote schemas via `/v1/metadata`
- **Query** — Run raw SQL, bulk operations, and migration commands via `/v1/query` and `/v2/query`
- **Health** — Check engine readiness and running version via /healthz and `/v1/version`

## Why Jentic

- **Setup:** Wiring Hasura by hand means targeting your own project host, and sending the admin-scoped X-Hasura-Admin-Secret header on every GraphQL and metadata call. Through Jentic you install once, import the Hasura GraphQL Engine API from the API Directory, store the admin secret once, and your agent calls it.
- **Permission scoping:** Hasura routes queries and metadata changes through a small set of POST endpoints (`/v1/graphql`, `/v1/metadata`, `/v1/query`), so scope the agent to the operations it needs, such as running a GraphQL query, rather than to one table. You choose the operations it may call, so metadata changes on `/v1/metadata` are not included unless you add them.
- **Credential handling:** Your Hasura X-Hasura-Admin-Secret is stored once, encrypted, by your own Jentic One instance and injected as the header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run a graphql query on hasura' or 'track a hasura table', and Jentic returns the matching `/v1/graphql` or `/v1/metadata` operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Supabase API** — Supabase exposes Postgres through REST and GraphQL with built-in auth, while Hasura focuses purely on GraphQL with metadata-driven configuration
- **Cloudflare API** — Cloudflare sits in front of Hasura to terminate TLS, cache GraphQL responses, and apply WAF rules
- **GitHub API** — GitHub stores the Hasura metadata YAML and migration files that the API applies

## FAQ

### Why is there no official OpenAPI spec for Hasura GraphQL Engine API?

Hasura does not publish an OpenAPI specification because the engine is GraphQL-first. Jentic generates and maintains this spec so that AI agents and developers can call the GraphQL and metadata endpoints via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Hasura GraphQL Engine API use?

All endpoints accept the X-Hasura-Admin-Secret header as an apiKey scheme. The secret grants full admin access to the project, so Jentic stores it in the vault and injects it per request - agents never see the raw value.

### Can I track a new Postgres table with the Hasura GraphQL Engine API?

Yes. Send a metadata command with type pg_track_table to POST `/v1/metadata`, naming the schema and table. Hasura adds the table to the GraphQL schema and the change is reflected immediately in `/v1/graphql` introspection.

### What are the rate limits for the Hasura GraphQL Engine API?

Self-hosted Hasura has no built-in rate limit on `/v1/graphql` or `/v1/metadata`; throughput is bounded by the engine and underlying Postgres. Hasura Cloud projects apply per-plan API request limits, so check your project dashboard before high-volume workloads.

### How do I run a GraphQL query through Jentic?

Search Jentic for 'run a graphql query on hasura', load the `/v1/graphql` operation schema, and execute with your query string and variables. Jentic attaches the admin secret from the vault so the call works without exposing credentials to the agent.

### Is the Hasura GraphQL Engine API free to use?

The open-source Hasura engine is free to self-host, with no API charges. Hasura Cloud has a free tier and paid plans that bill on data passthrough and seat count - endpoint paths are identical across deployments.

### Can I limit what my agent is allowed to do with the Hasura GraphQL Engine API?

Yes. Because Jentic One is self-hosted by you, your own rules decide which Hasura operations the agent may call, so you can grant it only running a GraphQL query on POST `/v1/graphql` and withhold schema-changing calls to POST `/v1/metadata` or POST `/v1/query.` Metadata changes such as tracking tables are not available to the agent unless you explicitly add that operation. Your X-Hasura-Admin-Secret stays with your Jentic One instance and is attached at execution time, so the agent acts only within the operations you allow.