Skip to main content
Version: v2.x

Metadata API Reference: Actions

Introduction​

actions are user defined mutations with custom business logic.

Supported from

The metadata API is supported for versions v2.0.0 and above and replaces the older schema/metadata API.

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:

POST /v1/metadata 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​

KeyRequiredSchemaDescription
nametrueActionNameName of the action
definitiontrueActionDefinitionDefinition of the action
commentfalsetextcomment
Note

The GraphQL Types used in creating an action must be defined before via Custom Types

drop_action​

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

Drop an action create_user:

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

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

Args syntax​

KeyRequiredSchemaDescription
nametrueActionNameName of the action
clear_datafalsebooleanIf set to true and action kind is asynchronous, related data is deleted from catalog. (default: true)

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:

POST /v1/metadata 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"
}
}
}

Args syntax​

KeyRequiredSchemaDescription
nametrueActionNameName of the action
definitiontrueActionDefinitionDefinition of the action to be replaced

create_action_permission​

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

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

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

Args syntax​

KeyRequiredSchemaDescription
actiontrueActionNameName of the action
roletrueRoleNameName of the role
commentfalsetextcomment

drop_action_permission​

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

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

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

Args syntax​

KeyRequiredSchemaDescription
nametrueActionNameName of the action
roletrueRoleNameName of the role