Schema/Metadata API Reference: Actions (Deprecated)

:::caution Deprecation

In versions v2.0.0 and above, the schema/Metadata API is deprecated in favour of the schema API and the Metadata API.

Though for backwards compatibility, the schema/Metadata APIs will continue to function.

:::

Introduction

actions are user defined mutations with custom business logic.

create_action {#schema-metadata-create-action}

create_action is used to define an action. There shouldn't be an existing action with the same name.

Create a synchronous action with name create_user:

http

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type":"create_action",
   "args":{
      "name":"create_user",
      "definition":{
         "kind":"synchronous",
         "arguments":[
            {
               "name":"username",
               "type":"String!"
            },
            {
               "name":"email",
               "type":"String!"
            }
         ],
         "output_type":"User",
         "handler":"https://action.my_app.com/create-user",
         "timeout":60
      },
      "comment": "Custom action to create user"
   }
}

Args syntax {#schema-metadata-create-action-syntax}

Key	Required	Schema	Description
name	true	ActionName	Name of the action
definition	true	ActionDefinition	Definition of the action
comment	false	text	comment

drop_action {#schema-metadata-drop-action}

drop_action is used to remove an action. Permissions defined on the Actions are also dropped automatically.

Drop an action create_user:

http

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type":"drop_action",
   "args":{
      "name":"create_user",
      "clear_data": true
   }
}

Args syntax {#schema-metadata-drop-action-syntax}

Key	Required	Schema	Description
name	true	ActionName	Name of the action
clear_data	false	boolean	If set to `true` and action kind is `asynchronous`, related data is deleted from catalog. (default: `true`)

update_action {#schema-metadata-update-action}

update_action is used to update the definition of the action. Definition thus provided is replaced with existing one.

Update an action create_user by making it's kind to asynchronous:

http

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type":"update_action",
   "args":{
      "name":"create_user",
      "definition":{
         "kind":"asynchronous",
         "arguments":[
            {
               "name":"username",
               "type":"String!"
            },
            {
               "name":"email",
               "type":"String!"
            }
         ],
         "output_type":"User",
         "handler":"https://action.my_app.com/create-user"
      },
      "comment": "Custom action to create user",
   }
}

Args syntax {#schema-metadata-update-action-syntax}

Key	Required	Schema	Description
name	true	ActionName	Name of the action
definition	true	ActionDefinition	Definition of the action to be replaced
comment	false	text	comment

create_action_permission {#schema-metadata-create-action-permission}

create_action_permission is used to define a permission to make action visible for a role.

http

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "create_action_permission",
  "args": {
    "action": "create_user",
    "role": "user"
  }
}

Args syntax {#schema-metadata-create-action-permission-syntax}

Key	Required	Schema	Description
action	true	ActionName	Name of the action
role	true	RoleName	Name of the role
comment	false	text	comment

drop_action_permission {#schema-metadata-drop-action-permission}

drop_action_permission is used to drop a permission defined on an action.

http

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "drop_action_permission",
  "args": {
    "action": "create_user",
    "role": "user"
  }
}

Args syntax {#schema-metadata-drop-action-permission-syntax}

Key	Required	Schema	Description
name	true	ActionName	Name of the action
role	true	RoleName	Name of the role