Schema API Reference

Introduction

The schema API provides the following features:

  1. 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.

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

POST /v2/query HTTP/1.1

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

Request body

Query

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.

# 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.