Metadata API Reference (v2.0 and above)

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

Query

Key Required Schema Description
type true String Type of the query
resource_version false Integer Version of the resource that you are targeting for replacement
args true JSON Value The arguments to the query
version false Integer Version of the API (inferred by args structure)

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
pg_add_source pg_add_source_args 1 Add a Postgres database
pg_drop_source pg_drop_source_args 1 Remove a Postgres database
pg_track_table pg_track_table_args 1 Add a Postgres table/view with configuration
pg_untrack_table pg_untrack_table_args 1 Remove a Postgres table/view
pg_set_table_customization pg_set_table_customization_args 1 Set table customization of an already tracked Postgres table
pg_set_table_is_enum pg_set_table_is_enum_args 1 Set a tracked Postgres table as an enum table
pg_track_function pg_track_function_args 1 Add a Postgres SQL function with configuration
pg_untrack_function FunctionName 1 Remove a Postgres SQL function
pg_create_function_permission pg_create_function_permission_args 1 Create a Postgres function permission
pg_drop_function_permission pg_drop_function_permission_args 1 Drop an existing Postgres function permission
pg_create_object_relationship pg_create_object_relationship_args 1 Define a new object relationship between Postgres tables/views
pg_create_array_relationship pg_create_array_relationship_args 1 Define a new array relationship between Postgres tables/views
pg_drop_relationship pg_drop_relationship_args 1 Drop an existing Postgres relationship
pg_rename_relationship pg_rename_relationship_args 1 Modify name of an existing Postgres relationship
pg_set_relationship_comment pg_set_relationship_comment_args 1 Set comment on an existing Postgres relationship
pg_add_computed_field pg_add_computed_field_args 1 Add a computed field to a Postgres table/view
pg_drop_computed_field pg_drop_computed_field_args 1 Drop a Postgres computed field
pg_create_insert_permission pg_create_insert_permission_args 1 Specify insert permission for a Postgres table/view
pg_drop_insert_permission pg_drop_insert_permission_args 1 Remove existing insert permission for a Postgres table/view
pg_create_select_permission pg_create_select_permission_args 1 Specify select permission for a Postgres table/view
pg_drop_select_permission pg_drop_select_permission_args 1 Remove existing select permission for a Postgres table/view
pg_create_update_permission pg_create_update_permission_args 1 Specify update permission for a Postgres table/view
pg_drop_update_permission pg_drop_update_permission_args 1 Remove existing update permission for a Postgres table/view
pg_create_delete_permission pg_create_delete_permission_args 1 Specify delete permission for a Postgres table/view
pg_drop_delete_permission pg_drop_delete_permission_args 1 Remove existing delete permission for a Postgres table/view
pg_set_permission_comment pg_set_permission_comment_args 1 Set comment on an existing permission for a Postgres table/view
pg_create_event_trigger pg_create_event_trigger_args 1 Create or replace an event trigger on a Postgres table
pg_delete_event_trigger pg_delete_event_trigger_args 1 Delete an existing event trigger on a Postgres table
pg_redeliver_event pg_redeliver_event_args 1 Redeliver an existing event on a Postgres table
pg_invoke_event_trigger pg_invoke_event_trigger_args 1 Invoke a trigger with custom payload on a Postgres table
create_cron_trigger create_cron_trigger_args 1 Create a cron trigger
delete_cron_trigger delete_cron_trigger_args 1 Delete an existing cron trigger
create_scheduled_event create_scheduled_event_args 1 Create a new scheduled event
add_remote_schema add_remote_schema_args 1 Add a remote GraphQL server as a remote schema
remove_remote_schema remove_remote_schema_args 1 Remove an existing remote schema
reload_remote_schema reload_remote_schema_args 1 Reload schema of an existing remote schema
add_remote_schema_permissions add_remote_schema_permissions 1 Add permissions to a role of an existing remote schema
drop_remote_schema_permissions drop_remote_schema_permissions 1 Drop existing permissions defined for a role for a remote schema
create_remote_relationship create_remote_relationship_args 1 Create a remote relationship with an existing remote schema
update_remote_relationship update_remote_relationship_args 1 Update an existing remote relationship
delete_remote_relationship delete_remote_relationship_args 1 Delete an existing remote relationship
export_metadata Empty Object 1 Export the current metadata
export_metadata Empty Object 2 Export existing metadata with resource version included.
replace_metadata replace_metadata_args 1 Import and replace existing metadata
replace_metadata replace_metadata_args 2 Replace existing metadata with check against current resource_version.
reload_metadata Empty Object 1 Reload changes to the underlying Postgres DB
clear_metadata Empty Object 1 Clear/wipe-out the current metadata state form server
get_inconsistent_metadata Empty Object 1 List all inconsistent metadata objects
drop_inconsistent_metadata Empty Object 1 Drop all inconsistent metadata objects
create_query_collection create_query_collection_args 1 Create a query collection
drop_query_collection drop_query_collection_args 1 Drop a query collection
add_query_to_collection add_query_to_collection_args 1 Add a query to a given collection
drop_query_from_collection drop_query_from_collection_args 1 Drop a query from a given collection
add_collection_to_allowlist add_collection_to_allowlist_args 1 Add a collection to the allow-list
drop_collection_from_allowlist drop_collection_from_allowlist_args 1 Drop a collection from the allow-list
set_custom_types set_custom_types_args 1 Set custom GraphQL types
create_action create_action_args 1 Create an action
drop_action drop_action_args 1 Drop an action
update_action update_action_args 1 Update an action
create_action_permission create_action_permission_args 1 Create an action permission
drop_action_permission drop_action_permission_args 1 Drop an action permission
create_rest_endpoint create_rest_endpoint_args 1 Create a RESTified GraphQL Endpoint
drop_rest_endpoint drop_rest_endpoint_args 1 Drop a RESTified GraphQL Endpoint

See:

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