Skip to main content
Version: v2.x

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

KeyRequiredSchemaDescription
typetrueStringType of the query
argstrueJSON ValueThe arguments to the query
versionfalseIntegerVersion of the API (default: 1)

Request types

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

typeargsversionSynopsis
bulkQuery array1Execute multiple operations in a single query
run_sqlrun_sql_args1Run SQL directly on Postgres

Response structure

Status codeDescriptionResponse structure
200SuccessRequest specific
400Bad request{ "path" : String, "error" : String}
401Unauthorized{"error" : String}
500Internal 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.