.. meta:: :description: Hasura schema/metadata API reference :keywords: hasura, docs, schema/metadata API, API reference .. _schema_metadata_apis: Schema / Metadata API Reference =============================== .. contents:: Table of contents :backlinks: none :depth: 1 :local: Introduction ------------ The schema / metadata API provides the following features: 1. Execute SQL on the underlying Postgres database, supports schema modifying actions. 2. Modify Hasura metadata (permission rules and relationships). This is primarily intended to be used as an ``admin`` API to manage the Hasura schema and metadata. .. admonition:: Deprecation In versions ``v2.0.0`` and above, the schema/metadata API is deprecated in favour of the :ref:`schema API ` and the :ref:`metadata API `. Though for backwards compatibility, the schema/metadata APIs will continue to function. Endpoint -------- All requests are ``POST`` requests to the ``/v1/query`` endpoint. Request structure ----------------- .. code-block:: http POST /v1/query HTTP/1.1 { "type": "", "args": } Request body ^^^^^^^^^^^^ .. parsed-literal:: :ref:`Query ` .. _api_query: Query ***** .. list-table:: :header-rows: 1 * - 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: .. list-table:: :header-rows: 1 * - ``type`` - ``args`` - ``version`` - Synopsis * - **bulk** - :ref:`Query ` array - 1 - Execute multiple operations in a single query * - :ref:`run_sql` - :ref:`run_sql_args ` - 1 - Run SQL directly on Postgres * - :ref:`track_table` - :ref:`TableName ` - 1 - Add a table/view * - :ref:`track_table ` - :ref:`track_table_args ` - 2 - Add a table/view with configuration * - :ref:`set_table_customization ` - :ref:`set_table_customization_args ` - 1 - Set table customization of an already tracked table * - :ref:`set_table_custom_fields ` (deprecated) - :ref:`set_table_custom_fields_args ` - 2 - Set custom fields of an already tracked table (deprecated) * - :ref:`untrack_table` - :ref:`untrack_table_args ` - 1 - Remove a table/view * - :ref:`set_table_is_enum` - :ref:`set_table_is_enum_args ` - 1 - Set a tracked table as an enum table * - :ref:`track_function` - :ref:`FunctionName ` - 1 - Add an SQL function * - :ref:`track_function` - :ref:`track_function_args ` - 2 - Add an SQL function with configuration * - :ref:`untrack_function` - :ref:`FunctionName ` - 1 - Remove an SQL function * - :ref:`create_object_relationship` - :ref:`create_object_relationship_args ` - 1 - Define a new object relationship * - :ref:`create_array_relationship` - :ref:`create_array_relationship_args ` - 1 - Define a new array relationship * - :ref:`drop_relationship` - :ref:`drop_relationship_args ` - 1 - Drop an existing relationship * - :ref:`rename_relationship` - :ref:`rename_relationship_args ` - 1 - Modify name of an existing relationship * - :ref:`set_relationship_comment` - :ref:`set_relationship_comment_args ` - 1 - Set comment on an existing relationship * - :ref:`add_computed_field` - :ref:`add_computed_field_args ` - 1 - Add a computed field * - :ref:`drop_computed_field` - :ref:`drop_computed_field_args ` - 1 - Drop a computed field * - :ref:`create_insert_permission` - :ref:`create_insert_permission_args ` - 1 - Specify insert permission * - :ref:`drop_insert_permission` - :ref:`drop_insert_permission_args ` - 1 - Remove existing insert permission * - :ref:`create_select_permission` - :ref:`create_select_permission_args ` - 1 - Specify select permission * - :ref:`drop_select_permission` - :ref:`drop_select_permission_args ` - 1 - Remove existing select permission * - :ref:`create_update_permission` - :ref:`create_update_permission_args ` - 1 - Specify update permission * - :ref:`drop_update_permission` - :ref:`drop_update_permission_args ` - 1 - Remove existing update permission * - :ref:`create_delete_permission` - :ref:`create_delete_permission_args ` - 1 - Specify delete permission * - :ref:`drop_delete_permission` - :ref:`drop_delete_permission_args ` - 1 - Remove existing delete permission * - :ref:`set_permission_comment` - :ref:`set_permission_comment_args ` - 1 - Set comment on an existing permission * - :ref:`create_event_trigger` - :ref:`create_event_trigger_args ` - 1 - Create or replace an event trigger * - :ref:`delete_event_trigger` - :ref:`delete_event_trigger_args ` - 1 - Delete an existing event trigger * - :ref:`redeliver_event` - :ref:`redeliver_event_args ` - 1 - Redeliver an existing event * - :ref:`invoke_event_trigger` - :ref:`invoke_event_trigger_args ` - 1 - Invoke a trigger with custom payload * - :ref:`create_cron_trigger` - :ref:`create_cron_trigger_args ` - 1 - Create a cron trigger * - :ref:`delete_cron_trigger` - :ref:`delete_cron_trigger_args ` - 1 - Delete an existing cron trigger * - :ref:`create_scheduled_event` - :ref:`create_scheduled_event_args ` - 1 - Create a new scheduled event * - :ref:`add_remote_schema` - :ref:`add_remote_schema_args ` - 1 - Add a remote GraphQL server as a remote schema * - :ref:`update_remote_schema` - :ref:`update_remote_schema_args ` - 1 - Update the details for a remote schema * - :ref:`remove_remote_schema` - :ref:`remove_remote_schema_args ` - 1 - Remove an existing remote schema * - :ref:`reload_remote_schema` - :ref:`reload_remote_schema_args ` - 1 - Reload schema of an existing remote schema * - :ref:`add_remote_schema_permissions` - :ref:`add_remote_schema_permissions ` - 1 - Add permissions to a role of an existing remote schema * - :ref:`drop_remote_schema_permissions` - :ref:`drop_remote_schema_permissions ` - 1 - Drop existing permissions defined for a role for a remote schema * - :ref:`create_remote_relationship` - :ref:`create_remote_relationship_args ` - 1 - Create a remote relationship with an existing remote schema * - :ref:`update_remote_relationship` - :ref:`update_remote_relationship_args ` - 1 - Update an existing remote relationship * - :ref:`delete_remote_relationship` - :ref:`delete_remote_relationship_args ` - 1 - Delete an existing remote relationship * - :ref:`export_metadata` - :ref:`Empty Object` - 1 - Export the current metadata * - :ref:`replace_metadata` - :ref:`replace_metadata_args ` - 1 - Import and replace existing metadata * - :ref:`reload_metadata` - :ref:`reload_metadata_args ` - 1 - Reload changes to the underlying Postgres DB * - :ref:`clear_metadata` - :ref:`Empty Object` - 1 - Clear/wipe-out the current metadata state form server * - :ref:`get_inconsistent_metadata` - :ref:`Empty Object` - 1 - List all inconsistent metadata objects * - :ref:`drop_inconsistent_metadata` - :ref:`Empty Object` - 1 - Drop all inconsistent metadata objects * - :ref:`create_query_collection` - :ref:`create_query_collection_args ` - 1 - Create a query collection * - :ref:`drop_query_collection` - :ref:`drop_query_collection_args ` - 1 - Drop a query collection * - :ref:`add_query_to_collection` - :ref:`add_query_to_collection_args ` - 1 - Add a query to a given collection * - :ref:`drop_query_from_collection` - :ref:`drop_query_from_collection_args ` - 1 - Drop a query from a given collection * - :ref:`add_collection_to_allowlist` - :ref:`add_collection_to_allowlist_args ` - 1 - Add a collection to the allow-list * - :ref:`drop_collection_from_allowlist` - :ref:`drop_collection_from_allowlist_args ` - 1 - Drop a collection from the allow-list * - :ref:`set_custom_types` - :ref:`set_custom_types_args ` - 1 - Set custom GraphQL types * - :ref:`create_action` - :ref:`create_action_args ` - 1 - Create an action * - :ref:`drop_action` - :ref:`drop_action_args ` - 1 - Drop an action * - :ref:`update_action` - :ref:`update_action_args ` - 1 - Update an action * - :ref:`create_action_permission` - :ref:`create_action_permission_args ` - 1 - Create an action permission * - :ref:`drop_action_permission` - :ref:`drop_action_permission_args ` - 1 - Drop an action permission * - :ref:`create_rest_endpoint` - :ref:`create_rest_endpoint_args ` - 3 - Create a RESTified GraphQL Endpoint * - :ref:`drop_rest_endpoint` - :ref:`drop_rest_endpoint_args ` - 3 - Drop a RESTified GraphQL Endpoint **See:** - :ref:`Run SQL ` - :ref:`Tables/Views ` - :ref:`Custom SQL Functions ` - :ref:`Relationships ` - :ref:`Computed Fields ` - :ref:`Permissions ` - :ref:`Remote Schema Permissions ` - :ref:`Event Triggers ` - :ref:`Remote Schemas ` - :ref:`Query Collections ` - :ref:`Custom Types ` - :ref:`Actions ` - :ref:`Manage Metadata ` Response structure ------------------ .. list-table:: :widths: 10 10 30 :header-rows: 1 * - Status code - Description - Response structure * - ``200`` - Success - .. parsed-literal:: Request specific * - ``400`` - Bad request - .. code-block:: haskell { "path" : String, "error" : String } * - ``401`` - Unauthorized - .. code-block:: haskell { "error" : String } * - ``500`` - Internal server error - .. code-block:: haskell { "error" : String } Error codes ----------- .. csv-table:: :file: dataerrors.csv :widths: 10, 20, 70 :header-rows: 1 Disabling schema / 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. .. code-block:: bash # enable only graphql api, disable metadata and pgdump --enabled-apis="graphql" HASURA_GRAPHQL_ENABLED_APIS="graphql" See :ref:`server_flag_reference` for info on setting the above flag/env var. .. toctree:: :maxdepth: 1 :hidden: Run SQL Tables/Views Custom Functions Relationships Permissions Remote Schema Permissions Computed Fields Event Triggers Scheduled Triggers Remote Schemas Remote Relationships Query Collections RESTified GraphQL Endpoints Custom Types Actions Manage Metadata