Skip to main content
API docs by Redocly

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

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

Authorizations:
BearerAuth
path Parameters
userId
required
stringuser_([a-z0-9]+)

Responses

Response samples

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

Delete a user

Deletes a user. The API token must have the "Users > Write" scope.

Authorizations:
BearerAuth
path Parameters
userId
required
stringuser_([a-z0-9]+)

Responses

Update a user

Updates and returns the updated user. The API token must have the "Users > Write" scope.

Authorizations:
BearerAuth
path Parameters
userId
required
stringuser_([a-z0-9]+)
Request Body schema: application/json
required
Array of objects or objects or objects

The body of a request to update a user.

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.

Authorizations:
BearerAuth

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.

Authorizations:
BearerAuth
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: {}

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "active": true,
  • "metadata": { }
}

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.

Authorizations:
BearerAuth
path Parameters
userId
required
stringuser_([a-z0-9]+)
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.

Authorizations:
BearerAuth
path Parameters
userId
required
stringuser_([a-z0-9]+)
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.

Authorizations:
BearerAuth
path Parameters
userId
required
stringuser_([a-z0-9]+)
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.

Authorizations:
BearerAuth
path Parameters
userId
required
stringuser_([a-z0-9]+)
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.

Authorizations:
BearerAuth

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.

Authorizations:
BearerAuth
path Parameters
groupId
required
string^\d+$

The group's ID number

Responses

Get group

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

Authorizations:
BearerAuth
path Parameters
groupId
required
string^\d+$

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.

Authorizations:
BearerAuth
path Parameters
groupId
required
string^\d+$

The group's ID number

Request Body schema: application/json
required
Array of objects or objects or objects

A list of operations to apply to the group. 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": {
    }
}

Update group

Update the entire group and returns the updated group. The API token must have the "Groups > Write" scope.

Authorizations:
BearerAuth
path Parameters
groupId
required
string^\d+$

The group's ID number

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

The name of the group.

Array of objects
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.

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

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

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "members": [
    ],
  • "universal_app_access": "none",
  • "universal_resource_access": "none",
  • "universal_workflow_access": "none",
  • "user_invites": [
    ],
  • "user_list_access": true,
  • "audit_log_access": true,
  • "unpublished_release_access": true,
  • "usage_analytics_access": true,
  • "account_details_access": true,
  • "landing_page_app_id": "1eae01b1-49ee-4691-8d4d-b43ef1d7ece4"
}

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.

Authorizations:
BearerAuth

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.

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

The name of the group.

Array of objects
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.

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

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

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "members": [
    ],
  • "universal_app_access": "none",
  • "universal_resource_access": "none",
  • "universal_workflow_access": "none",
  • "user_invites": [
    ],
  • "user_list_access": true,
  • "audit_log_access": true,
  • "unpublished_release_access": true,
  • "usage_analytics_access": true,
  • "account_details_access": true,
  • "landing_page_app_id": "1eae01b1-49ee-4691-8d4d-b43ef1d7ece4"
}

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.

Authorizations:
BearerAuth
path Parameters
groupId
required
string^\d+$

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.

Authorizations:
BearerAuth
path Parameters
groupId
required
string^\d+$

The group's ID number

Request Body schema: application/json
required
Array of objects
Array
id
required
stringuser_([a-z0-9]+)
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.

Authorizations:
BearerAuth
path Parameters
groupId
required
string^\d+$

The group's ID number

userSid
required
stringuser_([a-z0-9]+)

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.

Authorizations:
BearerAuth
path Parameters
groupId
required
string^\d+$

The group's ID number

userInviteId
required
string^\d+$

The user invite's ID number

Responses

List folders 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+

Authorizations:
BearerAuth
Request Body schema: application/json
required
object or object
object_type
required
string
Enum: "folder" "app" "resource" "resource_configuration"

Responses

Request samples

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

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 within the folder.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object or object
required
object or object or object or 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 within the folder.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object or object
required
object or object or object or 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.

Authorizations:
BearerAuth

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.

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

The name of the folder.

parent_folder_id
string or null^(app|workflow|resource)_([0-9]\d*)$

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.

Authorizations:
BearerAuth
path Parameters
folderId
required
string^(app|workflow|resource)_([0-9]\d*)$

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.

Authorizations:
BearerAuth
path Parameters
folderId
required
string^(app|workflow|resource)_([0-9]\d*)$

The id of the folder

Responses

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.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object or object
required
object or object or object or 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 within the folder.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object or object
required
object or object or object or 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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth

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.

Authorizations:
BearerAuth
path Parameters
spaceId
required
string

Responses

Response samples

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

Delete a space

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

Authorizations:
BearerAuth
path Parameters
spaceId
required
string

The id of the space to delete.

Responses

Response samples

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

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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth

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.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object or object or object or object or object

This object represents the Source Control provider configuration for the organization or space. See https://docs.retool.com/source-control 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.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object or object or object or object or object

This object represents the Source Control provider configuration for the organization or space. See https://docs.retool.com/source-control 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.

Authorizations:
BearerAuth

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.

Authorizations:
BearerAuth

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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth

Responses

Response samples

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

Get deployment by id

Get the status of a deployment

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth

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.

Authorizations:
BearerAuth
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.

Responses

Request samples

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

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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth

Responses

Response samples

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

SSO

Set SSO configuration

Sets SSO configuration for organization or space. The API token must have the "Spaces > Write" scope.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object or object or object or object or object

This object represents the SSO configuration for an organization or space. See https://docs.retool.com/sso 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": {
    }
}

Permissions

List folders 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+

Authorizations:
BearerAuth
Request Body schema: application/json
required
object or object
object_type
required
string
Enum: "folder" "app" "resource" "resource_configuration"

Responses

Request samples

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

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 within the folder.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object or object
required
object or object or object or 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 within the folder.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object or object
required
object or object or object or 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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
path Parameters
accessRequestId
required
string^\d+$

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.

Authorizations:
BearerAuth
path Parameters
accessRequestId
required
string

The ID of the access request

Request Body schema: application/json
required
Array of objects

The body of a request to update an access request's status.

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

Authorizations:
BearerAuth

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

Authorizations:
BearerAuth
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": "user@example.com",
  • "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.

Authorizations:
BearerAuth
path Parameters
userInviteId
required
string^\d+$

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.

Authorizations:
BearerAuth
path Parameters
userInviteId
required
string^\d+$

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

Authorizations:
BearerAuth
path Parameters
userInviteId
required
string^\d+$

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

Authorizations:
BearerAuth
path Parameters
userInviteId
required
string^\d+$

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.

Authorizations:
BearerAuth
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" "rockset" "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
}

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.

Authorizations:
BearerAuth
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": {
    }
}

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.

Authorizations:
BearerAuth
path Parameters
required
string or string or string or string or string or string

The uuid for the resource.

Responses

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.

Authorizations:
BearerAuth
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" "rockset" "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
}

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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
path Parameters
configurationId
required
string <uuid>

The resource configuration id.

Responses

Resource configurations

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.

Authorizations:
BearerAuth
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" "rockset" "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
}

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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
path Parameters
configurationId
required
string <uuid>

The resource configuration id.

Responses

Environment

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.

Authorizations:
BearerAuth

Responses

Response samples

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

Authorizations:
BearerAuth
path Parameters
environmentId
required
string <uuid>

Responses

Response samples

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

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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth

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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
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.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

The ID of the configuration variable

Responses