Skip to main content
API docs by Redocly

Retool API (2.6.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.

Retool API Documentation

Users

Get a user

Returns the specified user. The API token must have the "Users > Read" scope.

path Parameters
userId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete a user

Disables a user from the organization. The API token must have the "Users > Write" scope.

path Parameters
userId
required
string

Responses

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
op
required
string
Value: "add"
path
required
string
value
any or null

A JSON value

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List users

Returns a list of users. The API token must have the "Users > Read" scope.

query Parameters
email
string

Email address of user

first_name
string

First name of user

last_name
string

Last name of user

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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

Content type
application/json
{
  • "email": "[email protected]",
  • "first_name": "string",
  • "last_name": "string",
  • "active": true,
  • "metadata": { },
  • "user_type": "default"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "name": "string",
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

User Attributes

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

Content type
application/json
{
  • "name": "string",
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "total_count": 0,
  • "next_token": "string",
  • "has_more": true
}

Groups

Delete group

Deletes a group with the given groupId. The API token must have the "Groups > Write" scope.

path Parameters
groupId
required
string

The group's ID number

Responses

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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
op
required
string
Value: "add"
path
required
string
value
any or null

A JSON value

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "name": "string",
  • "members": [
    ],
  • "universal_app_access": "none",
  • "universal_resource_access": "none",
  • "universal_workflow_access": "none",
  • "universal_query_library_access": "none",
  • "user_invites": [
    ],
  • "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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List groups

Get all permission groups for an organization or space. The API token must have the "Groups > Read" scope.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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

Content type
application/json
{
  • "name": "string",
  • "members": [
    ],
  • "universal_app_access": "none",
  • "universal_resource_access": "none",
  • "universal_workflow_access": "none",
  • "universal_query_library_access": "none",
  • "user_invites": [
    ],
  • "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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "userInviteIds": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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
id
required
string
is_group_admin
required
boolean
Default: false

Whether the user is a group admin

Responses

Request samples

Content type
application/json
{
  • "members": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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"
include_inherited_access
boolean

Responses

Request samples

Content type
application/json
{
  • "subject": {
    },
  • "object_type": "folder",
  • "include_inherited_access": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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 directly under the folder. However it does not grant or update access for subfolders and subsequent objects under them.

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

Content type
application/json
{
  • "subject": {
    },
  • "object": {
    },
  • "access_level": "own"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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 directly under the folder. However it does not revoke access for subfolders and subsequent objects under them.

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

Content type
application/json
{
  • "subject": {
    },
  • "object": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "total_count": 0,
  • "next_token": "string",
  • "has_more": true
}

Folders

List folders

Returns a list of folders. The API token must have the "Folders > Read" scope.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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

Content type
application/json
{
  • "name": "string",
  • "parent_folder_id": "string",
  • "folder_type": "app"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "recursive": true
}

Response samples

Content type
application/json
{
  • "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
op
required
string
Value: "add"
path
required
string
value
any or null

A JSON value

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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 directly under the folder. However it does not grant or update access for subfolders and subsequent objects under them.

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

Content type
application/json
{
  • "subject": {
    },
  • "object": {
    },
  • "access_level": "own"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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 directly under the folder. However it does not revoke access for subfolders and subsequent objects under them.

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

Content type
application/json
{
  • "subject": {
    },
  • "object": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "total_count": 0,
  • "next_token": "string",
  • "has_more": true
}

Spaces

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

Content type
application/json
{
  • "name": "string",
  • "domain": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "name": "string",
  • "domain": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete a space

Available for orgs with Spaces enabled. Delete a space by ID. The API token must have the "Spaces > Write" scope.

path Parameters
spaceId
required
string

The id of the space to delete.

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "message": "string"
}

Copy elements to another space

Available for orgs with Spaces enabled. Copies apps, queries, resources, and workflows from one space to another. 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

Content type
application/json
{
  • "resource_ids": [
    ],
  • "query_library_query_ids": [
    ],
  • "app_ids": [
    ],
  • "workflow_ids": [
    ],
  • "destination_space_id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Source Control

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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
required
object or object
provider
required
string
Value: "GitHub"
org
required
string

The user or organization to which the repository belongs to.

repo
required
string

The name of the repository you created to use with Retool.

default_branch
required
string

The default branch, e.g., main.

repo_version
string

Repositories using Toolscript are 2.0.0. Repositories using legacy YAML are 1.0.0.

Responses

Request samples

Content type
application/json
{
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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
required
object or object
provider
required
string
Value: "GitHub"
org
required
string

The user or organization to which the repository belongs to.

repo
required
string

The name of the repository you created to use with Retool.

default_branch
required
string

The default branch, e.g., main.

repo_version
string

Repositories using Toolscript are 2.0.0. Repositories using legacy YAML are 1.0.0.

Responses

Request samples

Content type
application/json
{
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete source control provider configuration

Deletes source control provider configuration for organization or space. The API token must have the "Source Control > Write" scope.

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "message": "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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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
commit_sha
required
string

The commit SHA to dry deploy

is_full_sync
boolean

Responses

Request samples

Content type
application/json
{
  • "deploy_params": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get a deployment

Get the status of a deployment.

path Parameters
id
required
string <uuid>

The deployment ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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
auto_branch_naming_enabled
boolean

When enabled, Retool automatically suggests a branch name on branch creation. Defaults to true.

custom_pull_request_template_enabled
boolean

When enabled, Retool will use the template specified to create pull requests. Defaults to false.

custom_pull_request_template
string

Pull requests created from Retool will use the template specified.

version_control_locked
boolean

When set to true, creates a read-only instance of Retool, where app editing is disabled. Defaults to false.

force_uuid_mapping
boolean

When set to true, creates a uuid mapping for protected elements to be used in the source control repo. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Lists all release manifests

Returns a list of all release manifests available in the source control repository. The API token must have the "Source control > Releases (Read)" scope.

This feature is in beta. Reach out to support if you’d like to join the beta.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get a specific release manifest

Returns the release manifest with the specified name from the source control repository if it exists. The API token must have the "Source control > Releases (Read)" scope.

This feature is in beta. Reach out to support if you’d like to join the beta.

path Parameters
manifestName
required
string

Identifier for the manifest of interest

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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 > Releases (Write)" scope.

This feature is in beta. Reach out to support if you’d like to join the beta.

path Parameters
manifestName
required
string

Identifier for the manifest of interest

Request Body schema: application/json
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

Content type
application/json
{
  • "manifest": {
    },
  • "commit_message": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete a release manifest

Push a branch to the source control repository that deletes the named release manifest. The API token must have the "Source control > Releases (Write)" scope.

This feature is in beta. Reach out to support if you’d like to join the beta.

path Parameters
manifestName
required
string

Identifier for the manifest of interest

Request Body schema: application/json
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

Content type
application/json
{
  • "commit_message": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Set release manifest

Push a branch to the source control repository that updates the release version of the specified app in the named release manifest. If the manifest does not already exist, it will be created in the branch. The API token must have the "Source control > Releases (Write)" scope.

This feature is in beta. Reach out to support if you’d like to join the beta.

path Parameters
appUuid
required
string <uuid>

The uuid to specify an app of interest within the release manifest. This should be the uuid found in the source control repository, which may differ from the organization specific uuid.

manifestName
required
string

Identifier for the manifest of interest

Request Body schema: application/json
required
string or string

The release version to set for the specified app in the named release manifest

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

Content type
application/json
{
  • "release": "27.18.0",
  • "commit_message": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete the entry for an app from a release manifest

Push a branch to the source control repository that deletes the entry for the specified app from the named release manifest. The API token must have the "Source control > Releases (Write)" scope.

This feature is in beta. Reach out to support if you’d like to join the beta.

path Parameters
appUuid
required
string <uuid>

The uuid to specify an app of interest within the release manifest. This should be the uuid found in the source control repository, which may differ from the organization specific uuid.

manifestName
required
string

Identifier for the manifest of interest

Request Body schema: application/json
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

Content type
application/json
{
  • "commit_message": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Lists all available releases for the given app.

Returns a list of the available releases for the app. The API token must have the "Source control > Releases (Read)" scope.

This feature is in beta. Reach out to support if you’d like to join the beta.

path Parameters
appUuid
required
string

The uuid of the app.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Create a release artifact

Push a branch to the source control repository that creates a new release artifact with the provided version for the app based on the latest version. The API token must have the "Source control > Releases (Write)" scope.

This feature is in beta. Reach out to support if you’d like to join the beta.

path Parameters
appUuid
required
string

The uuid of the app.

Request Body schema: application/json
release_version
required
string

The version of the release.

release_description
string

The description of the release.

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

Content type
application/json
{
  • "release_version": "1.0.0",
  • "release_description": "Updated theme for better consistency and dark mode support.",
  • "commit_message": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

App Themes

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete app theme

Deletes specified app theme for organization or space. The API token must have the "App Themes > Write" scope.

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "message": "string"
}

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

Content type
application/json
{
  • "id": 0,
  • "legacy_id": 0,
  • "name": "string",
  • "theme": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": 0,
  • "legacy_id": 0,
  • "name": "string",
  • "theme": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Apps

Delete app

Deletes an app with the given appId. The API token must have the "Apps > Write" scope.

path Parameters
appId
required
string <uuid>

The app ID.

Responses

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List apps

Get all apps for an organization or space. The API token must have the "Apps > Read" scope.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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

Content type
application/json
{
  • "app_id": "affd1d10-9538-4fc8-9e0b-4594a28c1335",
  • "new_app_name": "string",
  • "folder_id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

SSO

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
config_type
required
string
Value: "google"
google_client_id
required
string
google_client_secret
required
string
disable_email_password_login
required
boolean

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Remove SSO configuration

Removes SSO configuration for organization or space. The API token must have the "Spaces > Write" scope. Note that this will not remove the SSO configuration if it is configured via env variables.

Responses

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Permissions

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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"
include_inherited_access
boolean

Responses

Request samples

Content type
application/json
{
  • "subject": {
    },
  • "object_type": "folder",
  • "include_inherited_access": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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 directly under the folder. However it does not grant or update access for subfolders and subsequent objects under them.

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

Content type
application/json
{
  • "subject": {
    },
  • "object": {
    },
  • "access_level": "own"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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 directly under the folder. However it does not revoke access for subfolders and subsequent objects under them.

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

Content type
application/json
{
  • "subject": {
    },
  • "object": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "total_count": 0,
  • "next_token": "string",
  • "has_more": true
}

Access Request

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

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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
op
required
string
Value: "replace"
path
required
string
value
any or null

A JSON value

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

User Invite

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

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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

Content type
application/json
{
  • "email": "[email protected]",
  • "defaultGroupIds": [
    ],
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete user invite

Available from API version 2.4.0+ and onprem version 3.26.0+. Returns the deleted user invite. The API token must have the "Users > Write" scope.

path Parameters
userInviteId
required
string

The user invite's ID

Responses

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

Content type
application/json
{
  • "name": "string",
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Resources

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

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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

Content type
application/json
{
  • "type": "mysql",
  • "display_name": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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
op
required
string
Value: "replace"
path
required
string
value
any or null

A JSON value

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete resource

Available from API version 2.4.0+ and onprem version 3.28.0+. Deletes a resource with the given id. 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.

Responses

Resource Configurations

Get resource configurations

Available from API version 2.4.0+ and Self-hosted Retool 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

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "total_count": 0,
  • "next_token": "string",
  • "has_more": true
}

Resource configurations

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

Content type
application/json
{
  • "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
  • "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "resource": {
    },
  • "environment": {
    },
  • "options": {
    },
  • "created_at": "2019-02-08T11:45:48.899Z",
  • "updated_at": "2019-02-24T18:28:18.790Z"
}

Delete resource configuration

Available from API version 2.4.0+ and onprem version 3.34.0+. Deletes a resource configuration with the given id. The API token must have the "Resources > Write" scope.

path Parameters
configurationId
required
string <uuid>

The resource configuration id.

Responses

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
op
required
string
Value: "replace"
path
required
string
value
any or null

A JSON value

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Environments

Get 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

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "total_count": 0,
  • "next_token": "string",
  • "has_more": true
}

Create environment

Available on Retool version 3.123.0+. Creates and returns an environment. The API token must have the "Environments > Write" scope.

Request Body schema: application/json
name
required
string non-empty

The name of the environment.

description
string

A description for the environment.

color
required
string

The (hexadecimal) color of the environment.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "color": "#FFFFFF"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get an environment

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update an environment

Available on Retool version 3.123.0+. Update an environment name, description, or color. The API token must have the "Environments > Write" scope.

path Parameters
environmentId
required
string <uuid>
Request Body schema: application/json
required
Array of objects

A list of operations to apply to the environment. See the JSON PATCH specification for more details.

Array
op
required
string
Value: "replace"
path
required
string
value
any or null

A JSON value

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete environment

Available on Retool version 3.123.0+. Deletes an environment by ID. The API token must have the "Environments > Write" scope.

path Parameters
environmentId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "message": "string"
}

CustomComponentLibrary

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "total_count": 0,
  • "next_token": "string",
  • "has_more": true
}

Configuration Variables

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

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "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

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "secret": true,
  • "values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update a configuration variable

Update a 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 > Write" scope.

path Parameters
id
required
string <uuid>

The ID of the configuration variable

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

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "secret": true,
  • "values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete configuration variable

Deletes a 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 > Write" scope.

path Parameters
id
required
string <uuid>

The ID of the configuration variable

Responses

Observability

Create a new observability provider configuration

Create observability configuration for the organization and returns the created configuration. This will result in an error if configuration is already set. The API token must have the "Observability > Write" scope.

Request Body schema: application/json
required
object or object

Provider-specific configuration. For Datadog, provide an API key. For Sentry, provide a DSN.

enabled
required
boolean

When enabled, use this provider for apps observability monitoring.

Responses

Request samples

Content type
application/json
{
  • "config": {
    },
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get observability provider configurations

Get observability configurations for the organization. The API token must have the "Observability > Read" scope.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Update an observability provider configuration

Update observability configuration for the organization and returns the updated configuration. This will result in an error if no existing configuration found. The API token must have the "Observability > Write" scope.

path Parameters
configId
required
string <uuid>

The id of the observability configuration to update.

Request Body schema: application/json
object or object

Provider-specific configuration. For Datadog, provide an API key. For Sentry, provide a DSN.

enabled
boolean

When enabled, use this provider for apps observability monitoring.

Responses

Request samples

Content type
application/json
{
  • "config": {
    },
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete an observability provider configuration

Delete observability configuration for the organization. The API token must have the "Observability > Write" scope.

path Parameters
configId
required
string <uuid>

The id of the observability configuration to delete.

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "message": "string"
}

Send a test error event to the observability provider

Send a test error event to the observability provider. The API token must have the "Observability > Read" scope.

path Parameters
required
string or string

The observability provider name, either "Sentry" or "Datadog"

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Usage

List organizations

Returns a list of organizations that the token has scope to access. The API token must have the 'usage' scope. 'usage:organization' scope returns just the organization, 'usage:spaces' returns all the spaces under the admin organization, 'usage:license' returns all the organizations that use that license key.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "total_count": 0,
  • "next_token": "string",
  • "has_more": true
}

The usage summary for the selected organizations

The usage summary for the selected organizations. Contains information about usage like page saves, page views, active users, and the growth in those fields in the specified time range. The API token must have the 'usage' scope.

query Parameters
org_ids
string
Example: org_ids=org_id1,org_id2

A comma separated list of org ids to retrieve usage data for

start_date
required
string
Example: start_date=2024-01-15

The start date of the date range

end_date
string
Example: end_date=2024-01-30

The end date of the date range. If not specified, then minimum(start_date + 30 days, today - 1) is used.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

The app summaries for the selected organizations

The app summaries for the selected organizations. Contains information about the app like saves, views, unique editors and viewers in the specified time range. The API token must have the 'usage' scope.

query Parameters
org_ids
string
Example: org_ids=org_id1,org_id2

A comma separated list of org ids to retrieve usage data for

start_date
required
string
Example: start_date=2024-01-15

The start date of the date range

end_date
string
Example: end_date=2024-01-30

The end date of the date range. If not specified, then minimum(start_date + 30 days, today - 1) is used.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "total_count": 0,
  • "next_token": "string",
  • "has_more": true
}

The app details for the selected app and organizations

The detailed app usage for the selected organizations. Contains information about the app, including the breakdown of saves and views in the specified time range. The API token must have the 'usage' scope.

query Parameters
org_ids
string
Example: org_ids=org_id1,org_id2

A comma separated list of org ids to retrieve usage data for

start_date
required
string
Example: start_date=2024-01-15

The start date of the date range

end_date
string
Example: end_date=2024-01-30

The end date of the date range. If not specified, then minimum(start_date + 30 days, today - 1) is used.

app_name
required
string

The name of the app to retrieve usage data for

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

The summaries of user usage for the selected organizations

The summaries of the user including email, last active time, the number of apps viewed and edited, for the selected organizations in the specified time range. The API token must have the 'usage' scope.

query Parameters
org_ids
string
Example: org_ids=org_id1,org_id2

A comma separated list of org ids to retrieve usage data for

start_date
required
string
Example: start_date=2024-01-15

The start date of the date range

end_date
string
Example: end_date=2024-01-30

The end date of the date range. If not specified, then minimum(start_date + 30 days, today - 1) is used.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "total_count": 0,
  • "next_token": "string",
  • "has_more": true
}

The user details for the selected user and organizations

Detailed usage by user for the selected organizations. Contains information about the user, including the breakdown of saves and views for apps in the specified time range. The API token must have the 'usage' scope.

query Parameters
org_ids
string
Example: org_ids=org_id1,org_id2

A comma separated list of org ids to retrieve usage data for

start_date
required
string
Example: start_date=2024-01-15

The start date of the date range

end_date
string
Example: end_date=2024-01-30

The end date of the date range. If not specified, then minimum(start_date + 30 days, today - 1) is used.

email
required
string

The email of the user to retrieve usage data for

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

UserTasks

List User Tasks

Returns a list of user tasks for a particular user. The API token must have the "User Tasks > Read" scope.

query Parameters
Array of strings or string

Filter tasks by assignment. Provide one or more user IDs. If not provided, returns all accessible tasks.

statuses
string
workflow_ids
string
limit
string

The maximum number of tasks included in a response.

next_token
string

The next token from the previous API response. This is used for paginating through an arbitrary number of tasks.

starting_after
string

The UUID of the task following which the response will include subsequent tasks.

ending_before
string

The UUID of the task before which the response will include preceding tasks.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "total_count": 0,
  • "next_token": "string",
  • "has_more": true
}

Completes a user task.

Completes a user task with a provided output payload. The API token must have the "User Tasks > Write" scope.

path Parameters
taskId
required
string <uuid>

The ID of the user task.

Request Body schema: multipart/form-data
email
required
string <email>

Email of user completing the task.

required
object

Assignee-defined output required for a task to be submitted.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Cancels a user task.

Cancel a user task with a provided reason. The API token must have the "User Tasks > Write" scope.

path Parameters
taskId
required
string <uuid>

The ID of the user task.

Request Body schema: multipart/form-data
email
required
string <email>

Email of user cancelling the task.

object

Assignee-defined output required for a task to be cancelled.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Reassign a user task to a group or a user.

Reassigns a user task to a group or user based on the group or user id. The API token must have the "User Tasks > Write" scope.

path Parameters
taskId
required
string <uuid>

The ID of the user task.

Request Body schema: multipart/form-data
email
required
string <email>

Email of user reassigning the task.

required
Array of objects or objects

New assignees. Can be group or user. Object of the arrays should look like { type: "group" or "user", id: 1 }

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

WorkflowRun

Get Workflow Run Details

Returns data for a workflow run. To retrieve user task information, the API token must have the "User Tasks > Read" scope.

query Parameters
id
required
string <uuid>

The ID of the workflow run.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "workflow_id": "03e70e31-d7a4-4401-a629-6a4b6096cdfe",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "trigger_type": "string",
  • "trigger_id": "5727dbbb-3b26-4abe-aec6-181eabbdb21c",
  • "created_at": "string",
  • "user_tasks": [
    ]
}