Schema API Reference

Introduction

The schema API provides the following features:

Execute SQL on the underlying Postgres database, supports schema modifying actions.

This is primarily intended to be used as an admin API to manage the Hasura schema.

:::tip Supported from

The schema API is supported for versions v2.0.0 and above and replaces the older schema/Metadata API.

:::

Endpoint

All requests are POST requests to the /v2/query endpoint.

Request structure

http

POST /v2/query HTTP/1.1

{
   "type": "<query-type>",
   "args": <args-object>
}

Request body

Query

Query {#schema-query}

Key	Required	Schema	Description
type	true	String	Type of the query
args	true	JSON Value	The arguments to the query
version	false	Integer	Version of the API (default: 1)

Request types

The various types of queries are listed in the following table:

`type`	`args`	`version`	Synopsis
bulk	Query array	1	Execute multiple operations in a single query
run_sql	run_sql_args	1	Run SQL directly on Postgres

Response structure

Status code	Description	Response structure
200	Success	Request specific
400	Bad request	`{ "path" : String, "error" : String}`
401	Unauthorized	`{"error" : String}`
500	Internal server error	`{"error" : String}`

Disabling schema API

Since this API can be used to make changes to the GraphQL schema, it can be disabled, especially in production deployments.

The enabled-apis flag or the HASURA_GRAPHQL_ENABLED_APIS env var can be used to enable/disable this API. By default, the schema/Metadata API is enabled. To disable it, you need to explicitly state that this API is not enabled i.e. remove it from the list of enabled APIs.

bash

# enable only graphql api, disable Metadata and pgdump
--enabled-apis="graphql"
HASURA_GRAPHQL_ENABLED_APIS="graphql"

See GraphQL Engine server config reference for info on setting the above flag/env var.