Retool API (2.5.0)
Download OpenAPI specification:Download
Go to Settings > API to get started. Once you generate an API token, use bearer token authentication to make requests.
Get user
Returns the user. The API token must have the "Users > Read" scope.
path Parameters
userId required | string |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "id": "string",
- "legacy_id": 0,
- "email": "user@example.com",
- "active": true,
- "created_at": "2019-02-08T11:45:48.899Z",
- "last_active": "2019-02-08T11:45:48.899Z",
- "first_name": "string",
- "last_name": "string",
- "metadata": { },
- "is_admin": true,
- "user_type": "default"
}
}
Update a user
Updates and returns the updated user. The API token must have the "Users > Write" scope.
path Parameters
userId required | string |
Request Body schema: application/json
required | Array of Add Operation (object) or Remove Operation (object) or Replace Operation (object) A list of operations to apply to the user. See the JSON PATCH specification for more details. | ||||||
Array Any of
|
Responses
Request samples
- Payload
{- "operations": [
- {
- "op": "add",
- "path": "string",
- "value": null
}
]
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": "string",
- "legacy_id": 0,
- "email": "user@example.com",
- "active": true,
- "created_at": "2019-02-08T11:45:48.899Z",
- "last_active": "2019-02-08T11:45:48.899Z",
- "first_name": "string",
- "last_name": "string",
- "metadata": { },
- "is_admin": true,
- "user_type": "default"
}
}
List users
Returns a list of users. The API token must have the "Users > Read" scope.
query Parameters
string Email address of user | |
first_name | string First name of user |
last_name | string Last name of user |
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "id": "string",
- "legacy_id": 0,
- "email": "user@example.com",
- "active": true,
- "created_at": "2019-02-08T11:45:48.899Z",
- "last_active": "2019-02-08T11:45:48.899Z",
- "first_name": "string",
- "last_name": "string",
- "metadata": { },
- "is_admin": true,
- "user_type": "default"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Create user
Creates a user and returns the created user. The API token must have the "Users > Write" scope.
Request Body schema: application/json
email required | string <email> The email of the user |
first_name required | string non-empty The first name of the user |
last_name required | string non-empty The last name of the user |
active | boolean Default: true Whether the user is enabled or not |
object Default: {} | |
user_type | string Enum: "default" "mobile" "embed" The user type |
Responses
Request samples
- Payload
{- "email": "user@example.com",
- "first_name": "string",
- "last_name": "string",
- "active": true,
- "metadata": { },
- "user_type": "default"
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": "string",
- "legacy_id": 0,
- "email": "user@example.com",
- "active": true,
- "created_at": "2019-02-08T11:45:48.899Z",
- "last_active": "2019-02-08T11:45:48.899Z",
- "first_name": "string",
- "last_name": "string",
- "metadata": { },
- "is_admin": true,
- "user_type": "default"
}
}
Add or update a user attribute
Available from API version 2.1.0+ and onprem version 3.20.1+. Adds or updates a user attribute, and returns the updated user metadata. The API token must have the "Users > Write" scope.
path Parameters
userId required | string |
Request Body schema: application/json
name required | string The name of the user attribute (must match an existing attribute exactly) |
value required | string or null The value of the user attribute |
Responses
Request samples
- Payload
{- "name": "string",
- "value": "string"
}
Response samples
- 200
{- "success": true,
- "data": {
- "metadata": { }
}
}
Delete a user attribute.
Available from API version 2.1.0+ and onprem version 3.20.1+. Deletes a user attribute, and returns the updated user metadata. The API token must have the "Users > Write" scope.
path Parameters
userId required | string |
attributeName required | string The name of the user attribute to delete |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "metadata": { }
}
}
Add or update a user attribute
Available from API version 2.1.0+ and onprem version 3.20.1+. Adds or updates a user attribute, and returns the updated user metadata. The API token must have the "Users > Write" scope.
path Parameters
userId required | string |
Request Body schema: application/json
name required | string The name of the user attribute (must match an existing attribute exactly) |
value required | string or null The value of the user attribute |
Responses
Request samples
- Payload
{- "name": "string",
- "value": "string"
}
Response samples
- 200
{- "success": true,
- "data": {
- "metadata": { }
}
}
Delete a user attribute.
Available from API version 2.1.0+ and onprem version 3.20.1+. Deletes a user attribute, and returns the updated user metadata. The API token must have the "Users > Write" scope.
path Parameters
userId required | string |
attributeName required | string The name of the user attribute to delete |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "metadata": { }
}
}
Get organization user attributes.
Gets the list of currently configured user attributes for the organization. The API token must have the "Users > Read" scope.
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "label": "string",
- "data_type": "string",
- "default_value": "string",
- "intercom_attribute_name": "string"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Get group
Get a group with a given groupId. The API token must have the "Groups > Read" scope.
path Parameters
groupId required | string The group's ID number |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "id": 0,
- "legacy_id": 0,
- "name": "string",
- "members": [
- {
- "id": "string",
- "email": "user@example.com",
- "is_group_admin": false
}
], - "universal_app_access": "none",
- "universal_resource_access": "none",
- "universal_workflow_access": "none",
- "universal_query_library_access": "none",
- "user_invites": [
- {
- "id": 0,
- "legacy_id": 0,
- "invited_by": "string",
- "invited_email": "user@example.com",
- "expires_at": "string",
- "claimed_by": "string",
- "claimed_at": "string",
- "user_type": "default",
- "metadata": { },
- "created_at": "string",
}
], - "user_list_access": true,
- "audit_log_access": true,
- "unpublished_release_access": true,
- "usage_analytics_access": true,
- "theme_access": true,
- "account_details_access": true,
- "landing_page_app_id": "1eae01b1-49ee-4691-8d4d-b43ef1d7ece4",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Update group
Update a group in an organization using JSON Patch (RFC 6902). Returns the updated group. The API token must have the "Groups > Write" scope.
path Parameters
groupId required | string The group's ID number |
Request Body schema: application/json
required | Array of Add Operation (object) or Remove Operation (object) or Replace Operation (object) A list of operations to apply to the group. See the JSON PATCH specification for more details. | ||||||
Array Any of
|
Responses
Request samples
- Payload
{- "operations": [
- {
- "op": "add",
- "path": "string",
- "value": null
}
]
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": 0,
- "legacy_id": 0,
- "name": "string",
- "members": [
- {
- "id": "string",
- "email": "user@example.com",
- "is_group_admin": false
}
], - "universal_app_access": "none",
- "universal_resource_access": "none",
- "universal_workflow_access": "none",
- "universal_query_library_access": "none",
- "user_invites": [
- {
- "id": 0,
- "legacy_id": 0,
- "invited_by": "string",
- "invited_email": "user@example.com",
- "expires_at": "string",
- "claimed_by": "string",
- "claimed_at": "string",
- "user_type": "default",
- "metadata": { },
- "created_at": "string",
}
], - "user_list_access": true,
- "audit_log_access": true,
- "unpublished_release_access": true,
- "usage_analytics_access": true,
- "theme_access": true,
- "account_details_access": true,
- "landing_page_app_id": "1eae01b1-49ee-4691-8d4d-b43ef1d7ece4",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Update group
Update the entire group and returns the updated group. The API token must have the "Groups > Write" scope.
path Parameters
groupId required | string The group's ID number |
Request Body schema: application/json
name | string non-empty The name of the group. |
Array of objects Users to add to the group. Pass in an empty list to create a group with no members. | |
universal_app_access | string Enum: "none" "use" "edit" "own" The universal app access level for the group. This denotes the access level that this group has for all apps. |
universal_resource_access | string Enum: "none" "use" "edit" "own" The universal resource access level for the group. This denotes the access level that this group has for all resources. |
universal_workflow_access | string Enum: "none" "use" "edit" "own" The universal workflow access level for the group. This denotes the access level that this group has for all workflows. |
universal_query_library_access | string Enum: "none" "use" "edit" Level of access that the group has to the Query Library. |
Array of objects A list of user invites that will be added to the group | |
user_list_access | boolean Whether the group has access to the user list |
audit_log_access | boolean Whether the group has access to the audit log |
unpublished_release_access | boolean Whether the group has access to unpublished releases |
usage_analytics_access | boolean Whether the group has access to usage analytics |
theme_access | boolean Whether the group has access to edit themes |
account_details_access | boolean Whether the group has access to account details |
landing_page_app_id | string or null <uuid> The app ID of the landing page |
created_at | string |
updated_at | string |
Responses
Request samples
- Payload
{- "name": "string",
- "members": [
- {
- "id": "string",
- "is_group_admin": false
}
], - "universal_app_access": "none",
- "universal_resource_access": "none",
- "universal_workflow_access": "none",
- "universal_query_library_access": "none",
- "user_invites": [
- {
- "id": 0,
- "legacy_id": 0,
- "invited_by": "string",
- "invited_email": "user@example.com",
- "expires_at": "string",
- "claimed_by": "string",
- "claimed_at": "string",
- "user_type": "default",
- "metadata": { },
- "created_at": "string",
}
], - "user_list_access": true,
- "audit_log_access": true,
- "unpublished_release_access": true,
- "usage_analytics_access": true,
- "theme_access": true,
- "account_details_access": true,
- "landing_page_app_id": "1eae01b1-49ee-4691-8d4d-b43ef1d7ece4",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": 0,
- "legacy_id": 0,
- "name": "string",
- "members": [
- {
- "id": "string",
- "email": "user@example.com",
- "is_group_admin": false
}
], - "universal_app_access": "none",
- "universal_resource_access": "none",
- "universal_workflow_access": "none",
- "universal_query_library_access": "none",
- "user_invites": [
- {
- "id": 0,
- "legacy_id": 0,
- "invited_by": "string",
- "invited_email": "user@example.com",
- "expires_at": "string",
- "claimed_by": "string",
- "claimed_at": "string",
- "user_type": "default",
- "metadata": { },
- "created_at": "string",
}
], - "user_list_access": true,
- "audit_log_access": true,
- "unpublished_release_access": true,
- "usage_analytics_access": true,
- "theme_access": true,
- "account_details_access": true,
- "landing_page_app_id": "1eae01b1-49ee-4691-8d4d-b43ef1d7ece4",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
List groups
Get all permission groups for an organization or space. The API token must have the "Groups > Read" scope.
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "id": 0,
- "legacy_id": 0,
- "name": "string",
- "members": [
- {
- "id": "string",
- "email": "user@example.com",
- "is_group_admin": false
}
], - "universal_app_access": "none",
- "universal_resource_access": "none",
- "universal_workflow_access": "none",
- "universal_query_library_access": "none",
- "user_invites": [
- {
- "id": 0,
- "legacy_id": 0,
- "invited_by": "string",
- "invited_email": "user@example.com",
- "expires_at": "string",
- "claimed_by": "string",
- "claimed_at": "string",
- "user_type": "default",
- "metadata": { },
- "created_at": "string",
}
], - "user_list_access": true,
- "audit_log_access": true,
- "unpublished_release_access": true,
- "usage_analytics_access": true,
- "theme_access": true,
- "account_details_access": true,
- "landing_page_app_id": "1eae01b1-49ee-4691-8d4d-b43ef1d7ece4",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Create group
Creates a group and returns the created group. The API token must have the "Groups > Write" scope.
Request Body schema: application/json
name required | string non-empty The name of the group. |
Array of objects Users to add to the group. Pass in an empty list to create a group with no members. | |
universal_app_access | string Enum: "none" "use" "edit" "own" The universal app access level for the group. This denotes the access level that this group has for all apps. |
universal_resource_access | string Enum: "none" "use" "edit" "own" The universal resource access level for the group. This denotes the access level that this group has for all resources. |
universal_workflow_access | string Enum: "none" "use" "edit" "own" The universal workflow access level for the group. This denotes the access level that this group has for all workflows. |
universal_query_library_access | string Enum: "none" "use" "edit" Level of access that the group has to the Query Library. |
Array of objects A list of user invites that will be added to the group | |
user_list_access | boolean Whether the group has access to the user list |
audit_log_access | boolean Whether the group has access to the audit log |
unpublished_release_access | boolean Whether the group has access to unpublished releases |
usage_analytics_access | boolean Whether the group has access to usage analytics |
theme_access | boolean Whether the group has access to edit themes |
account_details_access | boolean Whether the group has access to account details |
landing_page_app_id | string or null <uuid> The app ID of the landing page |
created_at | string |
updated_at | string |
Responses
Request samples
- Payload
{- "name": "string",
- "members": [
- {
- "id": "string",
- "is_group_admin": false
}
], - "universal_app_access": "none",
- "universal_resource_access": "none",
- "universal_workflow_access": "none",
- "universal_query_library_access": "none",
- "user_invites": [
- {
- "id": 0,
- "legacy_id": 0,
- "invited_by": "string",
- "invited_email": "user@example.com",
- "expires_at": "string",
- "claimed_by": "string",
- "claimed_at": "string",
- "user_type": "default",
- "metadata": { },
- "created_at": "string",
}
], - "user_list_access": true,
- "audit_log_access": true,
- "unpublished_release_access": true,
- "usage_analytics_access": true,
- "theme_access": true,
- "account_details_access": true,
- "landing_page_app_id": "1eae01b1-49ee-4691-8d4d-b43ef1d7ece4",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": 0,
- "legacy_id": 0,
- "name": "string",
- "members": [
- {
- "id": "string",
- "email": "user@example.com",
- "is_group_admin": false
}
], - "universal_app_access": "none",
- "universal_resource_access": "none",
- "universal_workflow_access": "none",
- "universal_query_library_access": "none",
- "user_invites": [
- {
- "id": 0,
- "legacy_id": 0,
- "invited_by": "string",
- "invited_email": "user@example.com",
- "expires_at": "string",
- "claimed_by": "string",
- "claimed_at": "string",
- "user_type": "default",
- "metadata": { },
- "created_at": "string",
}
], - "user_list_access": true,
- "audit_log_access": true,
- "unpublished_release_access": true,
- "usage_analytics_access": true,
- "theme_access": true,
- "account_details_access": true,
- "landing_page_app_id": "1eae01b1-49ee-4691-8d4d-b43ef1d7ece4",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Add user invites to group
Available from API version 2.4.0+ and onprem version 3.28.0+. Adds a user invite to specified group and returns the group. The API token must have the "Groups > Write" scope.
path Parameters
groupId required | string The group's ID number |
Request Body schema: application/json
userInviteIds required | Array of numbers |
Responses
Request samples
- Payload
{- "userInviteIds": [
- 0
]
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": 0,
- "legacy_id": 0,
- "name": "string",
- "members": [
- {
- "id": "string",
- "email": "user@example.com",
- "is_group_admin": false
}
], - "universal_app_access": "none",
- "universal_resource_access": "none",
- "universal_workflow_access": "none",
- "universal_query_library_access": "none",
- "user_invites": [
- {
- "id": 0,
- "legacy_id": 0,
- "invited_by": "string",
- "invited_email": "user@example.com",
- "expires_at": "string",
- "claimed_by": "string",
- "claimed_at": "string",
- "user_type": "default",
- "metadata": { },
- "created_at": "string",
}
], - "user_list_access": true,
- "audit_log_access": true,
- "unpublished_release_access": true,
- "usage_analytics_access": true,
- "theme_access": true,
- "account_details_access": true,
- "landing_page_app_id": "1eae01b1-49ee-4691-8d4d-b43ef1d7ece4",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Add users to group
Adds a user to specified group and returns the group. Can optionally set or unset group admins by using the is_group_admin
property. The API token must have the "Groups > Write" scope.
path Parameters
groupId required | string The group's ID number |
Request Body schema: application/json
required | Array of objects Users to add to the group. Pass in an empty list to create a group with no members. | ||||
Array
|
Responses
Request samples
- Payload
{- "members": [
- {
- "id": "string",
- "is_group_admin": false
}
]
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": 0,
- "legacy_id": 0,
- "name": "string",
- "members": [
- {
- "id": "string",
- "email": "user@example.com",
- "is_group_admin": false
}
], - "universal_app_access": "none",
- "universal_resource_access": "none",
- "universal_workflow_access": "none",
- "universal_query_library_access": "none",
- "user_invites": [
- {
- "id": 0,
- "legacy_id": 0,
- "invited_by": "string",
- "invited_email": "user@example.com",
- "expires_at": "string",
- "claimed_by": "string",
- "claimed_at": "string",
- "user_type": "default",
- "metadata": { },
- "created_at": "string",
}
], - "user_list_access": true,
- "audit_log_access": true,
- "unpublished_release_access": true,
- "usage_analytics_access": true,
- "theme_access": true,
- "account_details_access": true,
- "landing_page_app_id": "1eae01b1-49ee-4691-8d4d-b43ef1d7ece4",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Remove user from group
Removes the user from the group and returns the group. The API token must have the "Groups > Write" scope.
path Parameters
groupId required | string The group's ID number |
userSid required | string |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "id": 0,
- "legacy_id": 0,
- "name": "string",
- "members": [
- {
- "id": "string",
- "email": "user@example.com",
- "is_group_admin": false
}
], - "universal_app_access": "none",
- "universal_resource_access": "none",
- "universal_workflow_access": "none",
- "universal_query_library_access": "none",
- "user_invites": [
- {
- "id": 0,
- "legacy_id": 0,
- "invited_by": "string",
- "invited_email": "user@example.com",
- "expires_at": "string",
- "claimed_by": "string",
- "claimed_at": "string",
- "user_type": "default",
- "metadata": { },
- "created_at": "string",
}
], - "user_list_access": true,
- "audit_log_access": true,
- "unpublished_release_access": true,
- "usage_analytics_access": true,
- "theme_access": true,
- "account_details_access": true,
- "landing_page_app_id": "1eae01b1-49ee-4691-8d4d-b43ef1d7ece4",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Remove user invite from group
Available from API version 2.4.0+ and onprem version 3.28.0+. Removes the user invite from the group. The API token must have the "Groups > Write" scope.
path Parameters
groupId required | string The group's ID number |
userInviteId required | string The user invite's ID number |
Responses
Get the access list of an app or folder
Returns the list of users/groups and corresponding access levels whom have access to a selected folder/page. The API token must have the "Permissions > Read" scope. Supported from onprem edge version 3.96.0+ and 3.114-stable+
path Parameters
objectId required | string |
objectType required | string Enum: "app" "folder" |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "group": [
- {
- "subject": {
- "id": "string",
- "type": "group"
}, - "sources": {
- "direct": true,
- "universal": true,
- "groups": [
- {
- "id": "string",
- "type": "group"
}
], - "inherited": {
- "id": "string",
- "type": "app"
}
}, - "accessLevel": "own"
}
], - "user": [
- {
- "subject": {
- "id": "string",
- "type": "group"
}, - "sources": {
- "direct": true,
- "universal": true,
- "groups": [
- {
- "id": "string",
- "type": "group"
}
], - "inherited": {
- "id": "string",
- "type": "app"
}
}, - "accessLevel": "own"
}
], - "userInvite": [
- {
- "subject": {
- "id": "string",
- "type": "group"
}, - "sources": {
- "direct": true,
- "universal": true,
- "groups": [
- {
- "id": "string",
- "type": "group"
}
], - "inherited": {
- "id": "string",
- "type": "app"
}
}, - "accessLevel": "own"
}
]
}
}
List objects a group can access
Returns the list of objects with corresponding access levels that a subject (group) has access to. The API token must have the "Permissions > Read" scope. Folders are supported from API version 2.0.0 + and onprem version 3.18+, apps are supported from API version 2.4.0+ and onprem version 3.26.0+, resources and resource_configurations are supported from onprem edge version 3.37.0+ and 3.47-stable+
Request Body schema: application/json
required | Group (object) or User (object) |
object_type required | string Enum: "folder" "app" "resource" "resource_configuration" |
Responses
Request samples
- Payload
{- "subject": {
- "type": "group",
- "id": 0
}, - "object_type": "folder"
}
Response samples
- 200
{- "success": true,
- "data": [
- {
- "type": "folder",
- "id": "string",
- "access_level": "own"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Grant permissions
Grant a group (subject) access to an object. Returns the updated list of objects with corresponding access levels that the subject has access to. The API token must have the "Permissions > Write" scope. Folders are supported from API version 2.0.0 + and onprem version 3.18+, apps are supported from API version 2.4.0+ and onprem version 3.34.0+, resources and resource_configurations are supported from onprem edge version 3.37.0+ and 3.47-stable+. Only subject type supported is groups. Also grants or updates access for all the objects within the folder.
Request Body schema: application/json
required | Group (object) or User (object) |
required | Folder (object) or App (object) or Resource (object) or Resource Configuration (object) |
access_level required | string Enum: "own" "edit" "use" The access level that the group should have for the object |
Responses
Request samples
- Payload
{- "subject": {
- "type": "group",
- "id": 0
}, - "object": {
- "type": "folder",
- "id": "string"
}, - "access_level": "own"
}
Response samples
- 200
{- "success": true,
- "data": [
- {
- "type": "folder",
- "id": "string",
- "access_level": "own"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Revoke permissions
Revoke access to an object for a group. Returns the updated list of objects with corresponding access levels that the subject has access to. The API token must have the "Permissions > Write" scope. Folders are supported from API version 2.0.0 + and onprem version 3.18+, apps are supported from API version 2.4.0+ and onprem version 3.34.0+, resources and resource_configurations are supported from onprem edge version 3.37.0+ and 3.47-stable+. Only subject type supported is groups. Also revokes access to all the objects within the folder.
Request Body schema: application/json
required | Group (object) or User (object) |
required | Folder (object) or App (object) or Resource (object) or Resource Configuration (object) |
Responses
Request samples
- Payload
{- "subject": {
- "type": "group",
- "id": 0
}, - "object": {
- "type": "folder",
- "id": "string"
}
}
Response samples
- 200
{- "success": true,
- "data": [
- {
- "type": "folder",
- "id": "string",
- "access_level": "own"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
List folders
Returns a list of folders. The API token must have the "Folders > Read" scope.
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "id": "string",
- "legacy_id": "string",
- "name": "string",
- "parent_folder_id": "string",
- "is_system_folder": true,
- "folder_type": "app",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Create folder
Creates and returns a folder. The API token must have the "Folders > Write" scope.
Request Body schema: application/json
name required | string non-empty The name of the folder. |
parent_folder_id | string or null The ID of the parent folder. |
folder_type required | string Enum: "app" "workflow" "resource" The type of the folder. |
Responses
Request samples
- Payload
{- "name": "string",
- "parent_folder_id": "string",
- "folder_type": "app"
}
Response samples
- 200
- 409
- 422
{- "success": true,
- "data": {
- "id": "string",
- "legacy_id": "string",
- "name": "string",
- "parent_folder_id": "string",
- "is_system_folder": true,
- "folder_type": "app",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Get a folder
Returns the folder with the given ID. The API token must have the "Folders > Read" scope.
path Parameters
folderId required | string The id of the folder |
Responses
Response samples
- 200
- 404
{- "success": true,
- "data": {
- "id": "string",
- "legacy_id": "string",
- "name": "string",
- "parent_folder_id": "string",
- "is_system_folder": true,
- "folder_type": "app",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Delete folder
Deletes a folder by ID. The API token must have the "Folders > Write" scope.
path Parameters
folderId required | string The id of the folder |
Request Body schema: application/json
recursive | boolean Should the folder's contents also be deleted? |
Responses
Request samples
- Payload
{- "recursive": true
}
Response samples
- 404
{- "success": false,
- "message": "string"
}
Update folder
Updates a folder by ID. The API token must have the "Folders > Write" scope.
path Parameters
folderId required | string The id of the folder |
Request Body schema: application/json
required | Array of Add Operation (object) or Remove Operation (object) or Replace Operation (object) or Move Operation (object) or Copy Operation (object) or Test Operation (object) A list of operations to apply to the folder. See https://tools.ietf.org/html/rfc6902 for details. | ||||||
Array Any of
|
Responses
Request samples
- Payload
{- "operations": [
- {
- "op": "add",
- "path": "string",
- "value": null
}
]
}
Response samples
- 200
- 404
- 409
- 422
{- "success": true,
- "data": {
- "id": "string",
- "legacy_id": "string",
- "name": "string",
- "parent_folder_id": "string",
- "is_system_folder": true,
- "folder_type": "app",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Grant permissions
Grant a group (subject) access to an object. Returns the updated list of objects with corresponding access levels that the subject has access to. The API token must have the "Permissions > Write" scope. Folders are supported from API version 2.0.0 + and onprem version 3.18+, apps are supported from API version 2.4.0+ and onprem version 3.34.0+, resources and resource_configurations are supported from onprem edge version 3.37.0+ and 3.47-stable+. Only subject type supported is groups. Also grants or updates access for all the objects within the folder.
Request Body schema: application/json
required | Group (object) or User (object) |
required | Folder (object) or App (object) or Resource (object) or Resource Configuration (object) |
access_level required | string Enum: "own" "edit" "use" The access level that the group should have for the object |
Responses
Request samples
- Payload
{- "subject": {
- "type": "group",
- "id": 0
}, - "object": {
- "type": "folder",
- "id": "string"
}, - "access_level": "own"
}
Response samples
- 200
{- "success": true,
- "data": [
- {
- "type": "folder",
- "id": "string",
- "access_level": "own"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Revoke permissions
Revoke access to an object for a group. Returns the updated list of objects with corresponding access levels that the subject has access to. The API token must have the "Permissions > Write" scope. Folders are supported from API version 2.0.0 + and onprem version 3.18+, apps are supported from API version 2.4.0+ and onprem version 3.34.0+, resources and resource_configurations are supported from onprem edge version 3.37.0+ and 3.47-stable+. Only subject type supported is groups. Also revokes access to all the objects within the folder.
Request Body schema: application/json
required | Group (object) or User (object) |
required | Folder (object) or App (object) or Resource (object) or Resource Configuration (object) |
Responses
Request samples
- Payload
{- "subject": {
- "type": "group",
- "id": 0
}, - "object": {
- "type": "folder",
- "id": "string"
}
}
Response samples
- 200
{- "success": true,
- "data": [
- {
- "type": "folder",
- "id": "string",
- "access_level": "own"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Create a space
Available for orgs with Spaces enabled. Creates a new child space and returns it. The API token must have the "Spaces > Write" scope.
Request Body schema: application/json
name required | string non-empty |
domain required | string non-empty The domain of the space. On Retool Cloud, specify subdomain of the space instead. |
object |
Responses
Request samples
- Payload
{- "name": "string",
- "domain": "string",
- "options": {
- "copy_sso_settings": true,
- "copy_branding_and_themes_settings": true,
- "users_to_copy_as_admins": [
- "string"
], - "create_admin_user": true
}
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "domain": "string",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
List spaces
Available for orgs with Spaces enabled. List all child spaces of the current space. The API token must have the "Spaces > Read" scope.
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "domain": "string",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Get space
Available for orgs with Spaces enabled. Get space by ID. The API token must have the "Spaces > Read" scope.
path Parameters
spaceId required | string |
Responses
Response samples
- 200
- 404
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "domain": "string",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Update space
Available for orgs with Spaces enabled. Update space by ID. The API token must have the "Spaces > Write" scope.
path Parameters
spaceId required | string |
Request Body schema: application/json
name required | string non-empty The name of the space. |
domain required | string non-empty The domain of the space. On Retool Cloud, specify subdomain of the space instead. |
Responses
Request samples
- Payload
{- "name": "string",
- "domain": "string"
}
Response samples
- 200
- 404
- 422
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "domain": "string",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Copies apps, queries, resources, and workflows from one space to another
Available for orgs with Spaces enabled. Copy elements by ID. The API token must have the "Spaces > Write" scope.
Request Body schema: application/json
required | Array of strings or strings List of resource uuids to copy to the new space. |
query_library_query_ids required | Array of strings <uuid> [ items <uuid > ] List of query library query uuids to copy to the new space. |
app_ids required | Array of strings <uuid> [ items <uuid > ] List of app or module uuids to copy to the new space. |
workflow_ids required | Array of strings <uuid> [ items <uuid > ] List of workflow ids to copy to the new space. |
destination_space_id required | string The id of the space to copy the elements to. |
Responses
Request samples
- Payload
{- "resource_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "query_library_query_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "app_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "workflow_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "destination_space_id": "string"
}
Response samples
- 201
- 404
{- "success": true,
- "data": {
- "resource_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "query_library_query_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "app_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "workflow_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
}
Get source control configuration
Returns the source control provider configuration for the organization or space. The API token must have the "Source Control > Read" scope.
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "config": {
- "type": "App",
- "app_id": "string",
- "installation_id": "string",
- "private_key": "string",
- "url": "string",
- "enterprise_api_url": "string"
}, - "provider": "GitHub",
- "org": "string",
- "repo": "string",
- "default_branch": "string",
- "repo_version": "string"
}
}
Create source control configuration
Create source control provider configuration for the organization or space and returns the created configuration. This will result in an error if configuration already is already set. The API token must have the "Source Control > Write" scope.
Request Body schema: application/json
required | GitHub (object) or GitLab (object) or AWS CodeCommit (object) or Bitbucket (object) or Azure Repos (object) This object represents the Source Control provider configuration for the organization or space. See docs for more information. | ||||||||||||
Any of
|
Responses
Request samples
- Payload
{- "config": {
- "config": {
- "type": "App",
- "app_id": "string",
- "installation_id": "string",
- "private_key": "string",
- "url": "string",
- "enterprise_api_url": "string"
}, - "provider": "GitHub",
- "org": "string",
- "repo": "string",
- "default_branch": "string",
- "repo_version": "string"
}
}
Response samples
- 200
- 400
- 409
{- "success": true,
- "data": {
- "config": {
- "type": "App",
- "app_id": "string",
- "installation_id": "string",
- "private_key": "string",
- "url": "string",
- "enterprise_api_url": "string"
}, - "provider": "GitHub",
- "org": "string",
- "repo": "string",
- "default_branch": "string",
- "repo_version": "string"
}
}
Set source control configuration
Creates or updates the source control provider configuration for the organization or space. This will overwrite any existing configuration. The API token must have the "Source Control > Write" scope.
Request Body schema: application/json
required | GitHub (object) or GitLab (object) or AWS CodeCommit (object) or Bitbucket (object) or Azure Repos (object) This object represents the Source Control provider configuration for the organization or space. See docs for more information. | ||||||||||||
Any of
|
Responses
Request samples
- Payload
{- "config": {
- "config": {
- "type": "App",
- "app_id": "string",
- "installation_id": "string",
- "private_key": "string",
- "url": "string",
- "enterprise_api_url": "string"
}, - "provider": "GitHub",
- "org": "string",
- "repo": "string",
- "default_branch": "string",
- "repo_version": "string"
}
}
Response samples
- 200
- 201
- 400
{- "success": true,
- "data": {
- "config": {
- "type": "App",
- "app_id": "string",
- "installation_id": "string",
- "private_key": "string",
- "url": "string",
- "enterprise_api_url": "string"
}, - "provider": "GitHub",
- "org": "string",
- "repo": "string",
- "default_branch": "string",
- "repo_version": "string"
}
}
Tests source control connection
Tests the connection to the source control provider. Returns a boolean for whether the connection was successful or not. The API token must have the "Source Control > Read" scope.
Responses
Response samples
- 200
- 422
{- "success": true,
- "data": {
- "success": false,
- "message": "string"
}
}
Test source control changes
Attempts to do a dry deployment (no db changes) on the instance with provided commit sha to see if those changes are valid.
Request Body schema: application/json
required | object | ||||
|
Responses
Request samples
- Payload
{- "deploy_params": {
- "commit_sha": "string",
- "is_full_sync": true
}
}
Response samples
- 200
{- "success": true,
- "data": {
- "success": false,
- "message": "string"
}
}
Trigger deployment of latest changes
Deploys the latest changes from the source control provider to the instance. You can use the GET /deployment/{id} endpoint to check the status of the deployment.
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "status": "PENDING_START"
}
}
Get source control settings
Returns the source control settings for the organization or space. The API token must have the "Source Control > Read" scope.
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "auto_branch_naming_enabled": true,
- "custom_pull_request_template_enabled": true,
- "custom_pull_request_template": "string",
- "version_control_locked": true,
- "force_uuid_mapping": true
}
}
Set source control settings
Creates or updates source control settings for the organization or space. This will overwrite existing settings. The API token must have the "Source Control > Write" scope.
Request Body schema: application/json
required | object | ||||||||||
|
Responses
Request samples
- Payload
{- "settings": {
- "auto_branch_naming_enabled": true,
- "custom_pull_request_template_enabled": true,
- "custom_pull_request_template": "string",
- "version_control_locked": true,
- "force_uuid_mapping": true
}
}
Response samples
- 200
- 201
- 400
{- "success": true,
- "data": {
- "auto_branch_naming_enabled": true,
- "custom_pull_request_template_enabled": true,
- "custom_pull_request_template": "string",
- "version_control_locked": true,
- "force_uuid_mapping": true
}
}
Get all release manifests
Returns a list of all release manifests available in the source control repository. The API token must have the "Source Control > Read" scope.
Responses
Response samples
- 200
- 400
{- "success": true,
- "data": {
- "manifests": [
- {
- "apps": [
- {
- "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
- "release": "string"
}
], - "version": "string",
- "name": "string"
}
]
}
}
Set release manifest
Push a branch to the source control repository that creates or updates the named release manifest. If the manifest exists, it will be overwritten in the branch. The API token must have the "Source Control > Write" scope.
path Parameters
manifest_name required | string Name of the manifest to update |
Request Body schema: application/json
required | object A list of source controlled elements and the corresponding version to publish for that element |
commit_message | string Message to use for the commit that updates the specified manifest. If a message is not provided, a default will be used. |
Responses
Request samples
- Payload
{- "manifest": {
- "apps": [
- {
- "uuid": "2ab90f76-c234-428e-9896-40c3a9bdbb2b",
- "release": "latest"
}, - {
- "uuid": "100186a5-d6cf-4476-8f84-7a71ab2fbef2",
- "release": "1.0.1"
}, - {
- "uuid": "200be837-2558-4f88-bb3b-07bea668c23e",
- "release": "27.18.0"
}
]
}, - "commit_message": "string"
}
Response samples
- 200
- 400
{- "success": true,
- "data": {
- "commit_sha": "string",
- "url": "string",
- "branch_name": "string"
}
}
Get app theme
Returns the app theme matching the ID for the organization or space. The API token must have the "App Themes > Read" scope.
path Parameters
id required | string |
Responses
Response samples
- 200
- 404
{- "success": true,
- "data": {
- "id": 0,
- "legacy_id": 0,
- "name": "string",
- "theme": {
- "property1": null,
- "property2": null
}
}
}
Create app theme
Creates and returns a new app theme. If a theme with the same name already exists, it returns 409 and does not modify the theme. The API token must have the "App Themes > Write" scope.
Request Body schema: application/json
id required | number |
legacy_id required | number |
name required | string The name of the app theme. |
required | object The theme object. |
Responses
Request samples
- Payload
{- "id": 0,
- "legacy_id": 0,
- "name": "string",
- "theme": {
- "property1": null,
- "property2": null
}
}
Response samples
- 200
- 409
{- "success": true,
- "data": {
- "id": 0,
- "legacy_id": 0,
- "name": "string",
- "theme": {
- "property1": null,
- "property2": null
}
}
}
Update app theme
Creates or updates an app theme and returns it. The API token must have the "App Themes > Write" scope.
Request Body schema: application/json
id required | number |
legacy_id required | number |
name required | string The name of the app theme. |
required | object The theme object. |
Responses
Request samples
- Payload
{- "id": 0,
- "legacy_id": 0,
- "name": "string",
- "theme": {
- "property1": null,
- "property2": null
}
}
Response samples
- 200
- 201
- 409
{- "success": true,
- "data": {
- "id": 0,
- "legacy_id": 0,
- "name": "string",
- "theme": {
- "property1": null,
- "property2": null
}
}
}
Get app
Available from API version 2.4.0+ and onprem version 3.28.0+. Returns the App. The API token must have the "Apps > Read" scope.
path Parameters
appId required | string <uuid> The app ID. |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "folder_id": "string",
- "protected": true,
- "synced": true,
- "shortlink": "string",
- "is_module": true,
- "is_mobile_app": true,
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
List apps
Get all apps for an organization or space. The API token must have the "Apps > Read" scope.
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "folder_id": "string",
- "protected": true,
- "synced": true,
- "shortlink": "string",
- "is_module": true,
- "is_mobile_app": true,
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Clone app
Make a copy of an existing app into a chosen folder (defaults to root if not provided). The API token must have the "Apps > Write" scope. Available on Retool versions 3.105.0+.
Request Body schema: application/json
app_id required | string <uuid> The app ID. |
new_app_name required | string non-empty The name of the new app |
folder_id | string The id of the folder |
Responses
Request samples
- Payload
{- "app_id": "affd1d10-9538-4fc8-9e0b-4594a28c1335",
- "new_app_name": "string",
- "folder_id": "string"
}
Response samples
- 200
- 404
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "folder_id": "string",
- "protected": true,
- "synced": true,
- "shortlink": "string",
- "is_module": true,
- "is_mobile_app": true,
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Set SSO configuration
Sets SSO configuration for organization or space. The API token must have the "Spaces > Write" scope.
Request Body schema: application/json
required | Google (object) or OIDC (object) or Google & OIDC (object) or SAML (object) or Google & SAML (object) This object represents the SSO configuration for an organization or space. See docs for more information. | ||||||||
One of
|
Responses
Request samples
- Payload
{- "data": {
- "config_type": "google",
- "google_client_id": "string",
- "google_client_secret": "string",
- "disable_email_password_login": true
}
}
Response samples
- 200
- 400
{- "success": true,
- "data": {
- "config_type": "google",
- "google_client_id": "string",
- "google_client_secret": "string",
- "disable_email_password_login": true
}
}
Get SSO configuration
Reads SSO configuration of organization or space. The API token must have the "Spaces > Read" scope. Note that this will not return the SSO configuration if it is configured via env variables.
Responses
Response samples
- 200
- 404
- 422
{- "success": true,
- "data": {
- "config_type": "google",
- "google_client_id": "string",
- "google_client_secret": "string",
- "disable_email_password_login": true
}
}
Get the access list of an app or folder
Returns the list of users/groups and corresponding access levels whom have access to a selected folder/page. The API token must have the "Permissions > Read" scope. Supported from onprem edge version 3.96.0+ and 3.114-stable+
path Parameters
objectId required | string |
objectType required | string Enum: "app" "folder" |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "group": [
- {
- "subject": {
- "id": "string",
- "type": "group"
}, - "sources": {
- "direct": true,
- "universal": true,
- "groups": [
- {
- "id": "string",
- "type": "group"
}
], - "inherited": {
- "id": "string",
- "type": "app"
}
}, - "accessLevel": "own"
}
], - "user": [
- {
- "subject": {
- "id": "string",
- "type": "group"
}, - "sources": {
- "direct": true,
- "universal": true,
- "groups": [
- {
- "id": "string",
- "type": "group"
}
], - "inherited": {
- "id": "string",
- "type": "app"
}
}, - "accessLevel": "own"
}
], - "userInvite": [
- {
- "subject": {
- "id": "string",
- "type": "group"
}, - "sources": {
- "direct": true,
- "universal": true,
- "groups": [
- {
- "id": "string",
- "type": "group"
}
], - "inherited": {
- "id": "string",
- "type": "app"
}
}, - "accessLevel": "own"
}
]
}
}
List objects a group can access
Returns the list of objects with corresponding access levels that a subject (group) has access to. The API token must have the "Permissions > Read" scope. Folders are supported from API version 2.0.0 + and onprem version 3.18+, apps are supported from API version 2.4.0+ and onprem version 3.26.0+, resources and resource_configurations are supported from onprem edge version 3.37.0+ and 3.47-stable+
Request Body schema: application/json
required | Group (object) or User (object) |
object_type required | string Enum: "folder" "app" "resource" "resource_configuration" |
Responses
Request samples
- Payload
{- "subject": {
- "type": "group",
- "id": 0
}, - "object_type": "folder"
}
Response samples
- 200
{- "success": true,
- "data": [
- {
- "type": "folder",
- "id": "string",
- "access_level": "own"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Grant permissions
Grant a group (subject) access to an object. Returns the updated list of objects with corresponding access levels that the subject has access to. The API token must have the "Permissions > Write" scope. Folders are supported from API version 2.0.0 + and onprem version 3.18+, apps are supported from API version 2.4.0+ and onprem version 3.34.0+, resources and resource_configurations are supported from onprem edge version 3.37.0+ and 3.47-stable+. Only subject type supported is groups. Also grants or updates access for all the objects within the folder.
Request Body schema: application/json
required | Group (object) or User (object) |
required | Folder (object) or App (object) or Resource (object) or Resource Configuration (object) |
access_level required | string Enum: "own" "edit" "use" The access level that the group should have for the object |
Responses
Request samples
- Payload
{- "subject": {
- "type": "group",
- "id": 0
}, - "object": {
- "type": "folder",
- "id": "string"
}, - "access_level": "own"
}
Response samples
- 200
{- "success": true,
- "data": [
- {
- "type": "folder",
- "id": "string",
- "access_level": "own"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Revoke permissions
Revoke access to an object for a group. Returns the updated list of objects with corresponding access levels that the subject has access to. The API token must have the "Permissions > Write" scope. Folders are supported from API version 2.0.0 + and onprem version 3.18+, apps are supported from API version 2.4.0+ and onprem version 3.34.0+, resources and resource_configurations are supported from onprem edge version 3.37.0+ and 3.47-stable+. Only subject type supported is groups. Also revokes access to all the objects within the folder.
Request Body schema: application/json
required | Group (object) or User (object) |
required | Folder (object) or App (object) or Resource (object) or Resource Configuration (object) |
Responses
Request samples
- Payload
{- "subject": {
- "type": "group",
- "id": 0
}, - "object": {
- "type": "folder",
- "id": "string"
}
}
Response samples
- 200
{- "success": true,
- "data": [
- {
- "type": "folder",
- "id": "string",
- "access_level": "own"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Get organization access requests
Available from API version 2.3.0+ and onprem version 3.24.0+. Gets a list of access requests. The API token must have the "Users > Read" scope.
query Parameters
status | string Enum: "PENDING" "APPROVED" "DENIED" The status of the access request |
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "id": 0,
- "status": "PENDING",
- "legacy_id": 0,
- "requesting_email": "string",
- "updated_by_id": "string"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Get access request
Available from API version 2.2.0+ and onprem version 3.24.0+. Returns the access request. The API token must have the "Users > Read" scope.
path Parameters
accessRequestId required | string The access request's ID number |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "id": 0,
- "status": "PENDING",
- "legacy_id": 0,
- "requesting_email": "string",
- "updated_by_id": "string"
}
}
Approve or deny an access request
Available from API version 2.3.0+ and onprem version 3.24.0+. Approve or deny an access request in your organization. The API token must have the "Users > Write" scope.
path Parameters
accessRequestId required | string The ID of the access request |
Request Body schema: application/json
required | Array of objects A list of operations to apply to the access request. See the JSON PATCH specification for more details. | ||||||
Array
|
Responses
Request samples
- Payload
{- "operations": [
- {
- "op": "replace",
- "path": "string",
- "value": null
}
]
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": 0,
- "status": "PENDING",
- "legacy_id": 0,
- "requesting_email": "string",
- "updated_by_id": "string"
}
}
Get organization user invites
Available from API version 2.3.0+ and onprem version 3.24.0+. Gets a list of user invites
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "id": 0,
- "legacy_id": 0,
- "invited_by": "string",
- "invited_email": "user@example.com",
- "expires_at": "string",
- "claimed_by": "string",
- "claimed_at": "string",
- "user_type": "default",
- "metadata": { },
- "created_at": "string",
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Create a new user invite
Available from API version 2.4.0+ and onprem version 3.28.0+. Create a new user invite
Request Body schema: application/json
email required | string <email> The email of the invitee |
defaultGroupIds | Array of numbers Group IDs to invite the user to |
object |
Responses
Request samples
- Payload
{- "email": "user@example.com",
- "defaultGroupIds": [
- 0
], - "metadata": {
- "property1": null,
- "property2": null
}
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": 0,
- "legacy_id": 0,
- "invited_by": "string",
- "invited_email": "user@example.com",
- "expires_at": "string",
- "claimed_by": "string",
- "claimed_at": "string",
- "user_type": "default",
- "metadata": { },
- "created_at": "string",
}
}
Get user invite
Available from API version 2.4.0+ and onprem version 3.26.0+. Returns the user invite. The API token must have the "Users > Read" scope.
path Parameters
userInviteId required | string The user invite's ID |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "id": 0,
- "legacy_id": 0,
- "invited_by": "string",
- "invited_email": "user@example.com",
- "expires_at": "string",
- "claimed_by": "string",
- "claimed_at": "string",
- "user_type": "default",
- "metadata": { },
- "created_at": "string",
}
}
Add or update user attributes on a user invite
Available from API version 2.4.0+ and onprem version 3.28.0+. Add or update the user attributes of a user invite
path Parameters
userInviteId required | string The user invite's ID |
Request Body schema: application/json
name required | string The name of the user attribute (must match an existing attribute exactly) |
value required | string or null The value of the user attribute |
Responses
Request samples
- Payload
{- "name": "string",
- "value": "string"
}
Response samples
- 200
{- "success": true,
- "data": {
- "metadata": { }
}
}
Delete a user attribute on a user invite
Available from API version 2.4.0+ and onprem version 3.28.0+. Delete a specified user attribute from an user invite
path Parameters
userInviteId required | string The user invite's ID |
attributeName required | string |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "metadata": { }
}
}
Get resources
Available from API version 2.4.0+ and onprem version 3.28.0+. Gets a paginated list of resources. The API token must have the "Resources > Read" scope.
query Parameters
next_token | string The token of the current page |
resource_type | string Enum: "airflow" "alloydb" "asana" "athena" "basecamp" "bigid" "bigquery" "cassandra" "circleci" "closeio" "cosmosdb" "couchdb" "databricks" "datadog" "datastore" "denodo" "dynamodb" "elasticsearch" "firebase" "front" "gcs" "github" "googleAnalytics" "googleMaps" "googleSearchConsole" "googlesheets" "graphql" "grpc" "hubspot" "jdbc" "jira" "lambda" "launchdarkly" "microsoftTeams" "mongodb" "mssql" "mysql" "notion" "onesignal" "openAI" "openapi" "oracledb" "postgresql" "presto" "redis" "redshift" "restapi" "rethinkdb" "retoolEmail" "retoolAI" "retoolDb" "retoolStorage" "s3" "salesforce" "saphana" "sendgrid" "shell" "slack" "slackopenapi" "smtp" "snowflake" "stripe" "twilio" "vertica" The type of resource. |
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "airflow",
- "display_name": "string",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Create a resource
Available from onprem version 3.72.0+. Creates a resource. The API token must have the "Resources > Write" scope.
Request Body schema: application/json
type required | string Enum: "mysql" "postgresql" "redshift" "restapi" "snowflake" The type of resource. |
display_name required | string non-empty |
required | Postgres Options (object) or MySQL Options (object) or Redshift Options (object) or Snowflake Options (object) or Rest API Options (object) |
Responses
Request samples
- Payload
{- "type": "mysql",
- "display_name": "string",
- "options": {
- "database_options": {
- "host": "string",
- "port": "string",
- "name": "string",
- "username": "string",
- "password": "string",
- "ssl_settings": {
- "enabled": true,
- "client_key": "string",
- "client_cert": "string",
- "ca_cert": "string"
}, - "ssh_tunnel_options": {
- "enabled": true,
- "host": "string",
- "port": "string",
- "username": "string",
- "password": "string",
- "private_key_name": "string"
}, - "disable_converting_queries_to_prepared_statements": true,
- "show_write_gui_only": true
}
}
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "airflow",
- "display_name": "string",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Get resource by id
Available from API version 2.4.0+ and onprem version 3.28.0+. Returns a specific resource. The API token must have the "Resources > Read" scope.
path Parameters
required | string or string or string or string or string or string The uuid for the resource. |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "airflow",
- "display_name": "string",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Update a resource
Updates and returns the updated resource. The API token must have the "Resources > Write" scope.
path Parameters
required | string or string or string or string or string or string The uuid for the resource. |
Request Body schema: application/json
required | Array of objects A list of operations to apply to the resource. See the JSON PATCH specification for more details. | ||||||
Array
|
Responses
Request samples
- Payload
{- "operations": [
- {
- "op": "replace",
- "path": "string",
- "value": null
}
]
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "airflow",
- "display_name": "string",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Get resource configurations
Available from API version 2.4.0+ and onprem version 3.34.0+. Gets a paginated list of resource configurations. The API token must have the "Resources > Read" scope.
query Parameters
next_token | string The token of the current page |
resource_type | string Enum: "airflow" "alloydb" "asana" "athena" "basecamp" "bigid" "bigquery" "cassandra" "circleci" "closeio" "cosmosdb" "couchdb" "databricks" "datadog" "datastore" "denodo" "dynamodb" "elasticsearch" "firebase" "front" "gcs" "github" "googleAnalytics" "googleMaps" "googleSearchConsole" "googlesheets" "graphql" "grpc" "hubspot" "jdbc" "jira" "lambda" "launchdarkly" "microsoftTeams" "mongodb" "mssql" "mysql" "notion" "onesignal" "openAI" "openapi" "oracledb" "postgresql" "presto" "redis" "redshift" "restapi" "rethinkdb" "retoolEmail" "retoolAI" "retoolDb" "retoolStorage" "s3" "salesforce" "saphana" "sendgrid" "shell" "slack" "slackopenapi" "smtp" "snowflake" "stripe" "twilio" "vertica" The type of resource. |
string or string or string or string or string or string The uuid for the resource. | |
environment_id | string <uuid> |
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "resource": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "airflow",
- "display_name": "string",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}, - "environment": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "color": "string",
- "default": true,
- "created_at": "string",
- "updated_at": "string"
}, - "options": {
- "database_options": {
- "host": "string",
- "port": "string",
- "name": "string",
- "username": "string",
- "password": "string",
- "ssl_settings": {
- "enabled": true,
- "client_key": "string",
- "client_cert": "string",
- "ca_cert": "string"
}, - "ssh_tunnel_options": {
- "enabled": true,
- "host": "string",
- "port": "string",
- "username": "string",
- "password": "string",
- "private_key_name": "string"
}, - "disable_converting_queries_to_prepared_statements": true,
- "show_write_gui_only": true
}
}, - "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Create resource configuration
Available from API version 2.4.0+ and onprem version 3.74 on-prem+. Creates a new resource configuration. The API token must have the "Resources > Write" scope.
Request Body schema: application/json
required | string or string or string or string or string or string A UUID that uniquely identifies a resource. This is also referenced within the Retool app. For example, when you edit a resource, the ID can be found in the url. |
environment_id required | string <uuid> A UUID that uniquely identifies an environment. |
required | Postgres Options (object) or MySQL Options (object) or Redshift Options (object) or Snowflake Options (object) or Rest API Options (object) |
Responses
Request samples
- Payload
{- "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
- "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",
- "options": {
- "database_options": {
- "host": "string",
- "port": "string",
- "name": "string",
- "username": "string",
- "password": "string",
- "ssl_settings": {
- "enabled": true,
- "client_key": "string",
- "client_cert": "string",
- "ca_cert": "string"
}, - "ssh_tunnel_options": {
- "enabled": true,
- "host": "string",
- "port": "string",
- "username": "string",
- "password": "string",
- "private_key_name": "string"
}, - "disable_converting_queries_to_prepared_statements": true,
- "show_write_gui_only": true
}
}
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "resource": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "airflow",
- "display_name": "string",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}, - "environment": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "color": "string",
- "default": true,
- "created_at": "string",
- "updated_at": "string"
}, - "options": {
- "database_options": {
- "host": "string",
- "port": "string",
- "name": "string",
- "username": "string",
- "password": "string",
- "ssl_settings": {
- "enabled": true,
- "client_key": "string",
- "client_cert": "string",
- "ca_cert": "string"
}, - "ssh_tunnel_options": {
- "enabled": true,
- "host": "string",
- "port": "string",
- "username": "string",
- "password": "string",
- "private_key_name": "string"
}, - "disable_converting_queries_to_prepared_statements": true,
- "show_write_gui_only": true
}
}, - "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Get resource configuration by id
Available from API version 2.4.0+ and onprem version 3.28.0+. Returns a specific resource configuration. The API token must have the "Resources > Read" scope.
path Parameters
configurationId required | string <uuid> The resource configuration id. |
Responses
Response samples
- 200
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "resource": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "airflow",
- "display_name": "string",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}, - "environment": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "color": "string",
- "default": true,
- "created_at": "string",
- "updated_at": "string"
}, - "options": {
- "database_options": {
- "host": "string",
- "port": "string",
- "name": "string",
- "username": "string",
- "password": "string",
- "ssl_settings": {
- "enabled": true,
- "client_key": "string",
- "client_cert": "string",
- "ca_cert": "string"
}, - "ssh_tunnel_options": {
- "enabled": true,
- "host": "string",
- "port": "string",
- "username": "string",
- "password": "string",
- "private_key_name": "string"
}, - "disable_converting_queries_to_prepared_statements": true,
- "show_write_gui_only": true
}
}, - "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
Update a resource configuration
Available from API version 2.4.0+ and onprem version 3.74 on-prem+. Updates the resource configuration with the given resource configuration id. The API token must have the "Resources > Write" scope.
path Parameters
configurationId required | string <uuid> The resource configuration id. |
Request Body schema: application/json
required | Array of objects A list of operations to apply to the resource configuration. See the JSON PATCH specification for more details. | ||||||
Array
|
Responses
Request samples
- Payload
{- "operations": [
- {
- "op": "replace",
- "path": "string",
- "value": null
}
]
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "resource": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "airflow",
- "display_name": "string",
- "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}, - "environment": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "color": "string",
- "default": true,
- "created_at": "string",
- "updated_at": "string"
}, - "options": {
- "database_options": {
- "host": "string",
- "port": "string",
- "name": "string",
- "username": "string",
- "password": "string",
- "ssl_settings": {
- "enabled": true,
- "client_key": "string",
- "client_cert": "string",
- "ca_cert": "string"
}, - "ssh_tunnel_options": {
- "enabled": true,
- "host": "string",
- "port": "string",
- "username": "string",
- "password": "string",
- "private_key_name": "string"
}, - "disable_converting_queries_to_prepared_statements": true,
- "show_write_gui_only": true
}
}, - "created_at": "2019-02-08T11:45:48.899Z",
- "updated_at": "2019-02-24T18:28:18.790Z"
}
}
Get organization environments
Available from API version 2.4.0+ and onprem version 3.28.0+. Gets a list of environments. The API token must have the "Environment > Read" scope.
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "color": "string",
- "default": true,
- "created_at": "string",
- "updated_at": "string"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Get an environment by id
Available from API version 2.4.0+ and onprem version 3.28.0+. Returns a single environment of the given uuid. The API token must have the "Environment > Read" scope.
path Parameters
environmentId required | string <uuid> |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "color": "string",
- "default": true,
- "created_at": "string",
- "updated_at": "string"
}
}
Get a single custom component libraries
Available on Retool Cloud and self-hosted Retool version 3.41.0+. Gets a single custom component library. The API token must have the "CustomComponent > Read" scope.
path Parameters
libraryId required | string <uuid> |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "label": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
}
Create a new custom component library
Available on Retool Cloud and self-hosted Retool version 3.41.0+. Creates a new custom component library The API token must have the "CustomComponent > Write" scope.
Request Body schema: application/json
id | string <uuid> Specifies a specific id to use for the library. Used for syncronizing libraries across Retool Instances. |
name required | string How the library will be referred to in Toolscript, and other code based usages. |
description required | string or null |
label required | string How the library will be referred to in the Retool UI. Should be human readable. |
Responses
Request samples
- Payload
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "label": "string"
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "label": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
}
Get a list of all custom component libraries
Available on Retool Cloud and self-hosted Retool version 3.41.0+. Gets a paginated list of all custom component libraries. The API token must have the "CustomComponent > Read" scope.
query Parameters
next_token | string The token of the current page |
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "label": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Create a new custom component library revision
Available on Retool Cloud and self-hosted Retool version 3.41.0+. Creates a new version of a custom component library, the underlying files that describe the component. The API token must have the "CustomComponent > Write" scope.
path Parameters
libraryId required | string |
Request Body schema: multipart/form-data
id | string <uuid> Specifies a specific id to use for the library. Used for syncronizing libraries across Retool Instances. |
version_bump required | string Enum: "minor" "major" "dev" "specify_version" |
version | string A specific version tag to use. Also specify version_bump as 'specify_version'. |
files required | string <binary> |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "version": "string",
- "custom_component_library_id": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
}
Gets a list of all the revisions of a custom component library
Available on Retool Cloud and self-hosted Retool version 3.41.0+. Gets a list of all the revisions of a custom component library. The API token must have the "CustomComponent > Read" scope.
path Parameters
libraryId required | string <uuid> |
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "version": "string",
- "custom_component_library_id": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Gets all files associated with a custom component library revision.
Available on Retool Cloud and self-hosted Retool version 3.41.0+. Gets all files associated with a custom component library revision. The API token must have the "CustomComponent > Read" scope.
path Parameters
libraryId required | string <uuid> |
revisionId required | string <uuid> |
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "filepath": "string",
- "file_contents": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
List configuration variables and their values
Available for orgs with configuration variables enabled on Retool Version 3.42+. The API token must have the "Configuration Variables > Read" scope.
Responses
Response samples
- 200
{- "success": true,
- "data": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "secret": true,
- "values": [
- {
- "environment_id": "string",
- "value": "string"
}
]
}
], - "total_count": 0,
- "next_token": "string",
- "has_more": true
}
Create a configuration variable
Available for orgs with configuration variables enabled on Retool Version 3.42+. The API token must have the "Configuration Variables > Write" scope.
Request Body schema: application/json
name required | string The name of the configuration variable |
description | string The description of the configuration variable |
secret required | boolean Whether the configuration variable is a secret |
required | Array of objects |
Responses
Request samples
- Payload
{- "name": "string",
- "description": "string",
- "secret": true,
- "values": [
- {
- "environment_id": "string",
- "value": "string"
}
]
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "secret": true,
- "values": [
- {
- "environment_id": "string",
- "value": "string"
}
]
}
}
Retreive a single configuration variable and its values
Available for orgs with configuration variables enabled on Retool Version 3.42+. The API token must have the "Configuration Variables > Read" scope.
path Parameters
id required | string <uuid> The ID of the configuration variable |
Responses
Response samples
- 200
{- "success": true,
- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "secret": true,
- "values": [
- {