Skip to main content
Version: v2.x

Metadata API Reference

Introduction

The Metadata API is primarily intended to be used as an admin API to manage the Hasura Metadata.

Supported from

The Metadata 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 /v1/metadata endpoint.

Request structure

POST /v1/metadata HTTP/1.1

{
"type": <query-type>,
"version": <Integer> (optional),
"resource_version": <Integer> (optional),
"args": <args-object>
}

The structure of args depends on the type and version.

Request body

Query

KeyRequiredSchemaDescription
typetrueStringType of the query
resource_versionfalseIntegerVersion of the resource that you are targeting for replacement
argstrueJSON ValueThe arguments to the query
versionfalseIntegerVersion of the API (inferred by args structure)

Request types

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

See:

Response structure

Status codeDescriptionResponse structure
200SuccessRequest specific
400Bad request{ "path" : String, "error" : String}
401Unauthorized{"error" : String}
500Internal server error{"error" : String}

Disabling Metadata 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.

Metadata Resource Versioning

Metadata is versioned with an optional resource_version field in operations and responses.

This is intended to allow for feedback when replacing Metadata with modifications to an out-of-date copy.

The resource_version supplied must match the version returned otherwise a 409 error response is returned.

The version is incremented on any operation that modified Metadata as well as reload_metadata.