API Documentation
Home

Botpress API Documentation

Introduction

The Botpress API is a RESTful set of HTTP endpoints that allow you to create, deploy, and run chatbots on the Botpress Cloud (opens in a new tab).

It can be used to create and manage bots, handle conversations and messages, as well as to manage their content, users, and configuration.

The base URL of the Botpress Cloud API is: https://api.botpress.cloud

The API endpoints will expect the Content-type: application/json HTTP header to be present in the request and the request body (if any) to be in JSON format, and will send back the same header in the response and return a JSON response body as well.

Using the Botpress Client

If you're using JavaScript or TypeScript, we recommend using our official Botpress Client (opens in a new tab) to call our API, but if you're using another programming language or just want direct access to our REST API you can use this documentation as reference.

Authentication

To authenticate with the Botpress Cloud API, you'll need to use one of the methods below to obtain an access token.

These tokens can be used as a Bearer token to call all the endpoints of the API, by passing the following HTTP header to the API endpoints:

Authorization: Bearer {ACCESS_TOKEN}

Identity Token

  • Personal Access Token (PAT): Can be generated in the Profile Settings section of your Botpress Cloud account (opens in a new tab).
  • Bot Token: This will be provided to the bot (once deployed) in the BP_TOKEN environment variable.
  • Integration Token: This will be provided to the integration (once deployed) in the BP_TOKEN environment variable.

Pagination

The "List" endpoints of our API will return paginated results based on the creation date of the resource, with a default limit of 20 results per page.

When the number of results exceeds the limit, the response body will include a meta.nextToken property that can be passed as a query string parameter (e.g. endpoint?nextToken={nextToken}) to retrieve the next page of results.

If there are no more results, the endpoint will not provide a nextToken value.

Example:

  1. Call the /v1/chat/conversations endpoint to obtain the first page of results:
{
  "conversations": [
    (...)
  ],
  "meta": {
    "nextToken": "wwNgQn6tWNR/IHhKGHv/sg9zcIAGsxOk0TfmM+DdmcWkBZrXYjVvcfSZIZSs4ppCr/g="
  }
}
  1. Call the endpoint again but now passing the nextToken as a query string parameter, making sure the value is URL-encoded:
/v1/chat/conversations?nextToken=wwNgQn6tWNR%2FIHhKGHv%2Fsg9zcIAGsxOk0TfmM%2BDdmcWkBZrXYjVvcfSZIZSs4ppCr%2Fg%3D
  1. Repeat until the response body doesn't provide a nextToken value anymore:
{
  "conversations": [
    (...)
  ],
  "meta": {}
}

Errors

If an error occurs when calling an API endpoint, the response will return the appropriate HTTP status code as indicated below and the response body will be one of the following JSON objects indicating the nature of the error:

Unknown 

 {
  "type": "Unknown",
  "description": "An unknown error occurred",
  "status": 500
}

Internal 

 {
  "type": "Internal",
  "description": "An internal error occurred",
  "status": 500
}

Unauthorized 

 {
  "type": "Unauthorized",
  "description": "The request requires to be authenticated.",
  "status": 401
}

Forbidden 

 {
  "type": "Forbidden",
  "description": "The requested action can't be peform by this resource.",
  "status": 403
}

Payload Too Large 

 {
  "type": "PayloadTooLarge",
  "description": "The request payload is too large.",
  "status": 413
}

Invalid Payload 

 {
  "type": "InvalidPayload",
  "description": "The request payload is invalid.",
  "status": 400
}

Unsupported Media Type 

 {
  "type": "UnsupportedMediaType",
  "description": "The request is invalid because the content-type is not supported.",
  "status": 415
}

Method Not Found 

 {
  "type": "MethodNotFound",
  "description": "The requested method does not exist.",
  "status": 405
}

Resource Not Found 

 {
  "type": "ResourceNotFound",
  "description": "The requested resource does not exist.",
  "status": 404
}

Invalid Json Schema 

 {
  "type": "InvalidJsonSchema",
  "description": "The provided JSON schema is invalid.",
  "status": 400
}

Invalid Data Format 

 {
  "type": "InvalidDataFormat",
  "description": "The provided data doesn't respect the provided JSON schema.",
  "status": 400
}

Invalid Identifier 

 {
  "type": "InvalidIdentifier",
  "description": "The provided identifier is not valid. An identifier must start with a lowercase letter, be between 2 and 100 characters long and use only alphanumeric characters.",
  "status": 400
}

Relation Conflict 

 {
  "type": "RelationConflict",
  "description": "The resource is related with a different resource that the one referenced in the request. This is usually caused when providing two resource identifiers that aren't linked together.",
  "status": 409
}

Reference Constraint 

 {
  "type": "ReferenceConstraint",
  "description": "The resource cannot be deleted because it's referenced by another resource",
  "status": 409
}

Resource Locked Conflict 

 {
  "type": "ResourceLockedConflict",
  "description": "The resource is current locked and cannot be operated on until the lock is released.",
  "status": 409
}

Reference Not Found 

 {
  "type": "ReferenceNotFound",
  "description": "The provided resource reference is missing. This is usually caused when providing an invalid id inside the payload of a request.",
  "status": 400
}

Invalid Query 

 {
  "type": "InvalidQuery",
  "description": "The provided query is invalid. This is usually caused when providing an invalid parameter for querying a resource.",
  "status": 400
}

Runtime 

 {
  "type": "Runtime",
  "description": "An error happened during the execution of a runtime (bot or integration).",
  "status": 400
}

Already Exists 

 {
  "type": "AlreadyExists",
  "description": "The record attempted to be created already exists.",
  "status": 409
}

Rate Limited 

 {
  "type": "RateLimited",
  "description": "The request has been rate limited.",
  "status": 429
}

Payment Required 

 {
  "type": "PaymentRequired",
  "description": "A payment is required to perform this request.",
  "status": 402
}

Quota Exceeded 

 {
  "type": "QuotaExceeded",
  "description": "The request exceeds the allowed quota. Quotas are a soft limit that can be increased.",
  "status": 403
}

Limit Exceeded 

 {
  "type": "LimitExceeded",
  "description": "The request exceeds the allowed limit. Limits are a hard limit that cannot be increased.",
  "status": 413
}

Breaking Changes 

 {
  "type": "BreakingChanges",
  "description": "Request payload contains breaking changes which is not allowed for this resource without a version increment.",
  "status": 400
}

User

Endpoints
POST
/v1/chat/users
GET
/v1/chat/users/{id}
GET
/v1/chat/users
POST
/v1/chat/users/get-or-create
PUT
/v1/chat/users/{id}
DELETE
/v1/chat/users/{id}

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

  • x-bot-id: The ID of the bot that the User belongs to.

  • x-integration-id: When the endpoint is being called as an Integration, this should be the ID of the integration that's calling it.

The User object

Attributes

id : string

Id of the User

createdAt : string

Creation date of the User in ISO 8601 format

updatedAt : string

Updating date of the User in ISO 8601 format

tags : object of key-value pairs

Set of Tags that you can attach to a User. The set of Tags available on a User is restricted by the list of Tags defined previously by the Bot. Individual keys can be unset by posting an empty value to them.

name : string

Name of the User

pictureUrl : string

Picture URL of the User

Create User

POST
/v1/chat/users

Creates a new User. When creating a new User, the required tags must be provided. See the specific integration for more details.

Body

tags : object of key-value pairs

Tags for the User

name : string

Name of the user

pictureUrl : string

URI of the user picture

Response

Returns a User object if creation succeeds. Returns an Error otherwise

user : object (6)

Get User

GET
/v1/chat/users/{id}

Retrieves the User object for a valid identifier.

Path

id : string

User ID

Response

Returns a User object if a valid identifier was provided. Returns an Error otherwise

user : object (6)

List Users

GET
/v1/chat/users

Retrieves a list of User previously created. The users are returned in sorted order, with the most recent appearing first. The list can be filtered using Tags.

Query

nextToken : string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

conversationId : string

Filter by conversation id. This will return all users that have participated in the conversation.

tags : object

Filter by tags

Response

Returns a list of User objects

users : array of object

id : string

Id of the User

createdAt : string

Creation date of the User in ISO 8601 format

updatedAt : string

Updating date of the User in ISO 8601 format

tags : object of key-value pairs

Set of Tags that you can attach to a User. The set of Tags available on a User is restricted by the list of Tags defined previously by the Bot. Individual keys can be unset by posting an empty value to them.

name : string

Name of the User

pictureUrl : string

Picture URL of the User

meta : object (1)

Get Or Create User

POST
/v1/chat/users/get-or-create

Retrieves the User object for a valid identifier. If the user does not exist, it will be created.

Body

tags : object of key-value pairs

Tags for the User

name : string

Name of the user

pictureUrl : string

URI of the user picture

Response

Returns a User object if a valid identifier was provided. Returns an Error otherwise

user : object (6)

Update User

PUT
/v1/chat/users/{id}

Update a User object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Path

id : string

User ID

Body

tags : object of key-value pairs

Tags for the User

name : string

Name of the user

pictureUrl : string

URI of the user picture

Response

Returns an updated User object if a valid identifier was provided. Returns an error otherwise

user : object (6)

Delete User

DELETE
/v1/chat/users/{id}

Permanently deletes a User. It cannot be undone.

Path

id : string

User ID

Response

Returns the User object that was deleted

Conversation

Endpoints
POST
/v1/chat/conversations
GET
/v1/chat/conversations/{id}
GET
/v1/chat/conversations
POST
/v1/chat/conversations/get-or-create
PUT
/v1/chat/conversations/{id}
DELETE
/v1/chat/conversations/{id}
GET
/v1/chat/conversations/{id}/participants
POST
/v1/chat/conversations/{id}/participants
GET
/v1/chat/conversations/{id}/participants/{userId}
DELETE
/v1/chat/conversations/{id}/participants/{userId}

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

  • x-bot-id: The ID of the bot that the Conversation belongs to.

  • x-integration-id: When the endpoint is being called as an Integration, this should be the ID of the integration that's calling it.

The Conversation object

Attributes

id : string

Id of the Conversation

currentTaskId : string

Id of the current Task

createdAt : string

Creation date of the Conversation in ISO 8601 format

updatedAt : string

Updating date of the Conversation in ISO 8601 format

channel : string

Name of the channel where the Conversation is happening

integration : string

Name of the integration that created the Conversation

tags : object of key-value pairs

Set of Tags that you can attach to a Conversation. The set of Tags available on a Conversation is restricted by the list of Tags defined previously by the Bot. Individual keys can be unset by posting an empty value to them.

Create Conversation

POST
/v1/chat/conversations

Creates a new Conversation. When creating a new Conversation, the required tags must be provided. See the specific integration for more details.

Body

channel : string

Channel name

tags : object of key-value pairs

Tags for the Conversation

Response

Returns a Conversation object if creation succeeds. Returns an error otherwise

conversation : object (7)

Get Conversation

GET
/v1/chat/conversations/{id}

Retrieves the Conversation object for a valid identifier.

Path

id : string

Conversation id

Response

Returns a Conversation object if a valid identifier was provided. Returns an error otherwise

conversation : object (7)

List Conversations

GET
/v1/chat/conversations

Retrieves a list of Conversation you’ve previously created. The conversations are returned in sorted order, with the most recent appearing first. The list can be filtered using Tags.

Query

nextToken : string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

tags : object

Filter by tags

participantIds : array of string

Filter by participant ids

integrationName : string

Filter by integration name

Response

Returns a list of Conversation objects

conversations : array of object

id : string

Id of the Conversation

currentTaskId : string

Id of the current Task

createdAt : string

Creation date of the Conversation in ISO 8601 format

updatedAt : string

Updating date of the Conversation in ISO 8601 format

channel : string

Name of the channel where the Conversation is happening

integration : string

Name of the integration that created the Conversation

tags : object of key-value pairs

Set of Tags that you can attach to a Conversation. The set of Tags available on a Conversation is restricted by the list of Tags defined previously by the Bot. Individual keys can be unset by posting an empty value to them.

meta : object (1)

Get Or Create Conversation

POST
/v1/chat/conversations/get-or-create

Retrieves the Conversation object for a valid identifier. If the conversation does not exist, it will be created.

Body

channel : string

Channel name

tags : object of key-value pairs

Tags for the Conversation

Response

Returns a Conversation object if a valid identifier was provided. Returns an error otherwise

conversation : object (7)

Update Conversation

PUT
/v1/chat/conversations/{id}

Update a Conversation object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Path

id : string

Conversation id

Body

currentTaskId : string

tags : object of key-value pairs

Tags for the Conversation

Response

Returns an updated Conversation object if a valid identifier was provided. Returns an error otherwise

conversation : object (7)

Delete Conversation

DELETE
/v1/chat/conversations/{id}

Permanently deletes a Conversation. It cannot be undone. Also immediately deletes corresponding Messages.

Path

id : string

Conversation id

Response

Returns the Conversation object that was deleted

List Participants

GET
/v1/chat/conversations/{id}/participants

Retrieves a list of Participant for a given Conversation.

Query

nextToken : string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

Path

id : string

Conversation id

Response

Returns a list of Participant objects

participants : array of object

id : string

Id of the User

createdAt : string

Creation date of the User in ISO 8601 format

updatedAt : string

Updating date of the User in ISO 8601 format

tags : object of key-value pairs

Set of Tags that you can attach to a User. The set of Tags available on a User is restricted by the list of Tags defined previously by the Bot. Individual keys can be unset by posting an empty value to them.

name : string

Name of the User

pictureUrl : string

Picture URL of the User

meta : object (1)

Add Participant

POST
/v1/chat/conversations/{id}/participants

Add a Participant to a Conversation.

Path

id : string

Conversation id

Body

userId : string

User id

Response

Returns the Participant object

participant : object (6)

Get Participant

GET
/v1/chat/conversations/{id}/participants/{userId}

Retrieves a Participant from a Conversation.

Path

id : string

Conversation id

userId : string

User id

Response

Returns the Participant object

participant : object (6)

Remove Participant

DELETE
/v1/chat/conversations/{id}/participants/{userId}

Remove a Participant from a Conversation.

Path

id : string

Conversation id

userId : string

User id

Response

Returns an empty object

Event

Endpoints
POST
/v1/chat/events
GET
/v1/chat/events/{id}
GET
/v1/chat/events

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

  • x-bot-id: The ID of the bot that the Event belongs to.

  • x-integration-id: When the endpoint is being called as an Integration, this should be the ID of the integration that's calling it.

The Event object

Attributes

id : string

Id of the Event

createdAt : string

Creation date of the Event in ISO 8601 format

type : string

Type of the Event.

payload : object of key-value pairs

Payload is the content of the event defined by the integration installed on your bot or one of the default events created by our api.

conversationId : string

ID of the Conversation to link the event to.

userId : string

ID of the User to link the event to.

messageId : string

ID of the Message to link the event to.

status : string

Possible values: pending, processed, ignored, failed

failureReason : string

Reason why the event failed to be processed

Create Event

POST
/v1/chat/events

Creates a new Event. When creating a new Event, the required tags must be provided. See the specific integration for more details.

Body

type : string

Type of the Event.

payload : object of key-value pairs

Payload is the content of the event defined by the integration installed on your bot or one of the default events created by our API.

schedule : object (2)

conversationId : string

ID of the Conversation to link the event to.

userId : string

ID of the User to link the event to.

messageId : string

ID of the Message to link the event to.

Response

Returns a Event object if creation succeeds. Returns an error otherwise

event : object (9)

Get Event

GET
/v1/chat/events/{id}

Retrieves the Event object for a valid identifiers.

Path

id : string

Event id

Response

Returns the Event object if a valid identifiers were provided. Returns an error otherwise

event : object (9)

List Events

GET
/v1/chat/events

Retrieves a list of Event you’ve previously created. The events are returned in sorted order, with the most recent appearing first.

Query

nextToken : string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

type : string

Filter by event type

conversationId : string

Filter by conversation id

userId : string

Filter by user id

messageId : string

Filter by message id

status : string

Filter by status. Allowed values: pending, ignored, processed, failed.

Response

Returns a list of Event objects

events : array of object

id : string

Id of the Event

createdAt : string

Creation date of the Event in ISO 8601 format

type : string

Type of the Event.

payload : object of key-value pairs

Payload is the content of the event defined by the integration installed on your bot or one of the default events created by our api.

conversationId : string

ID of the Conversation to link the event to.

userId : string

ID of the User to link the event to.

messageId : string

ID of the Message to link the event to.

status : string

Possible values: pending, processed, ignored, failed

failureReason : string

Reason why the event failed to be processed

meta : object (1)

Message

Endpoints
POST
/v1/chat/messages
POST
/v1/chat/messages/get-or-create
GET
/v1/chat/messages/{id}
PUT
/v1/chat/messages/{id}
GET
/v1/chat/messages
DELETE
/v1/chat/messages/{id}

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

  • x-bot-id: The ID of the bot that the Message belongs to.

  • x-integration-id: When the endpoint is being called as an Integration, this should be the ID of the integration that's calling it.

The Message object

Attributes

id : string

Id of the Message

createdAt : string

Creation date of the Message in ISO 8601 format

type : string

Type of the Message represents the resource type that the message is related to

payload : object of key-value pairs

Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location

direction : string

Direction of the message (incoming or outgoing).

Possible values: incoming, outgoing

userId : string

ID of the User

conversationId : string

ID of the Conversation

tags : object of key-value pairs

Set of Tags that you can attach to a Conversation. The set of Tags available on a Conversation is restricted by the list of Tags defined previously by the Bot. Individual keys can be unset by posting an empty value to them.

Create Message

POST
/v1/chat/messages

Creates a new Message. When creating a new Message, the required tags must be provided. See the specific integration for more details.

Body

payload : object of key-value pairs

Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location

userId : string

ID of the User

conversationId : string

ID of the Conversation

type : string

Type of the Message represents the resource type that the message is related to

tags : object of key-value pairs

Set of Tags that you can attach to a Message. The set of Tags available on a Message is restricted by the list of Tags defined previously by the Bot. Individual keys can be unset by posting an empty value to them.

schedule : object (2)

Response

Returns a Message object if creation succeeds.

message : object (8)

Get Or Create Message

POST
/v1/chat/messages/get-or-create

Retrieves the Message object for a valid identifier. If the message does not exist, it will be created.

Body

payload : object of key-value pairs

Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location

userId : string

ID of the User

conversationId : string

ID of the Conversation

type : string

Type of the Message represents the resource type that the message is related to

tags : object of key-value pairs

Set of Tags that you can attach to a Message. The set of Tags available on a Message is restricted by the list of Tags defined previously by the Bot. Individual keys can be unset by posting an empty value to them.

schedule : object (2)

Response

Returns a Message object if a valid identifier was provided. Returns an Error otherwise

message : object (8)

Get Message

GET
/v1/chat/messages/{id}

Retrieves the Message object for a valid identifier.

Path

id : string

Id of the Message

Response

Returns a Message object if a valid identifier was provided. Returns an Error otherwise

message : object (8)

Update Message

PUT
/v1/chat/messages/{id}

Update a message

Path

id : string

Message id

Body

tags : object of key-value pairs

Set of Tags that you can attach to a Conversation. The set of Tags available on a Conversation is restricted by the list of Tags defined previously by the Bot. Individual keys can be unset by posting an empty value to them.

Response

Message information

message : object (8)

List Messages

GET
/v1/chat/messages

Retrieves a list of Message you’ve previously created. The messages are returned in sorted order, with the most recent appearing first. The list can be filtered using Tags.

Query

nextToken : string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

conversationId : string

Conversation id

tags : object

Filter by tags

Response

Returns a list of Message objects.

messages : array of object

id : string

Id of the Message

createdAt : string

Creation date of the Message in ISO 8601 format

type : string

Type of the Message represents the resource type that the message is related to

payload : object of key-value pairs

Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location

direction : string

Direction of the message (incoming or outgoing).

Possible values: incoming, outgoing

userId : string

ID of the User

conversationId : string

ID of the Conversation

tags : object of key-value pairs

Set of Tags that you can attach to a Conversation. The set of Tags available on a Conversation is restricted by the list of Tags defined previously by the Bot. Individual keys can be unset by posting an empty value to them.

meta : object (1)

Delete Message

DELETE
/v1/chat/messages/{id}

Permanently deletes a Message. It cannot be undone.

Path

id : string

Message id

Response

Returns the Message object that was deleted

State

Endpoints
GET
/v1/chat/states/{type}/{id}/{name}
POST
/v1/chat/states/{type}/{id}/{name}
POST
/v1/chat/states/{type}/{id}/{name}/get-or-set
PATCH
/v1/chat/states/{type}/{id}/{name}

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

  • x-bot-id: The ID of the bot that the State belongs to.

  • x-integration-id: When the endpoint is being called as an Integration, this should be the ID of the integration that's calling it.

The State object

Attributes

id : string

Id of the State

createdAt : string

Creation date of the State in ISO 8601 format

updatedAt : string

Updating date of the State in ISO 8601 format

botId : string

Id of the Bot

conversationId : string

Id of the Conversation

userId : string

Id of the User

name : string

Name of the State which is declared inside the bot definition

type : string

Type of the State represents the resource type (conversation, user, bot, task or integration) that the state is related to

Possible values: conversation, user, bot, task, integration

payload : object of key-value pairs

Payload is the content of the state defined by your bot.

Get State

GET
/v1/chat/states/{type}/{id}/{name}

Retrieves the State object for a valid identifiers.

Path

type : string

State type

id : string

State id

name : string

State name

Response

Returns the State object if a valid identifiers were provided. Returns an error otherwise

state : object (9)

Set State

POST
/v1/chat/states/{type}/{id}/{name}

Overrides the State object by setting the values of the parameters passed.

Path

type : string

State type

id : string

State id

name : string

State name

Body

payload : object of key-value pairs

Payload is the content of the state defined by your bot.

expiry : number

Expiry of the State in milliseconds. The state will expire if it is idle for the configured value. By default, a state doesn't expire.

Response

Returns the updated State object if a valid identifier was provided. Returns an an error otherwise

state : object (9)

Get Or Set State

POST
/v1/chat/states/{type}/{id}/{name}/get-or-set

Retrieves the State object for a valid identifiers. If the state does not exist, it creates a new state.

Path

type : string

State type

id : string

State id

name : string

State name

Body

payload : object of key-value pairs

Payload is the content of the state defined by your bot.

expiry : number

Expiry of the State in milliseconds. The state will expire if it is idle for the configured value. By default, a state doesn't expire.

Response

Returns the State object if a valid identifiers were provided. Returns an error otherwise.

state : object (9)

Patch State

PATCH
/v1/chat/states/{type}/{id}/{name}

Updates the State object by setting the values of the parameters passed.

Path

type : string

State type

id : string

State id

name : string

State name

Body

payload : object of key-value pairs

Payload is the content of the state defined by your bot.

Response

Returns the updated State object if a valid identifier was provided. Returns an an error otherwise

state : object (9)

Hub

Endpoints
GET
/v1/admin/hub/integrations
GET
/v1/admin/hub/integrations/{id}
GET
/v1/admin/hub/integrations/{name}/{version}

List Public Integrations

GET
/v1/admin/hub/integrations

List public integration

Query

nextToken : string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

name : string

Integration Name

version : string

Integration version. Either a semver version or tag "latest"

Response

Success

integrations : array of object

id : string

ID of the Integration

name : string

Name of the Integration

version : string

Version of the Integration

createdAt : string

Creation date of the Integration in ISO 8601 format

updatedAt : string

Updating date of the Integration in ISO 8601 format

title : string

Title of the integration. This is the name that will be displayed in the UI

description : string

Description of the integration. This is the description that will be displayed in the UI

iconUrl : string

URL of the icon of the integration. This is the icon that will be displayed in the UI

public : boolean

Idicates if the integration is public. Public integrations are available to all and cannot be updated without creating a new version.

ownerWorkspace : object (3)

meta : object (1)

Get Public Integration By Id

GET
/v1/admin/hub/integrations/{id}

Get public integration by Id

Path

id : string

Integration ID

Response

Success

integration : object (23)

Get Public Integration

GET
/v1/admin/hub/integrations/{name}/{version}

Get public integration by name and version

Path

name : string

Integration Name

version : string

Integration version. Either a semver version or tag "latest"

Response

Success

integration : object (23)

Action

Endpoints
POST
/v1/chat/actions

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

  • x-bot-id: The ID of the bot that the Action belongs to.

  • x-integration-id: When the endpoint is being called as an Integration, this should be the ID of the integration that's calling it.

Call Action

POST
/v1/chat/actions

Call an action

Body

type : string

Type of the action

input : object of key-value pairs

Input of the action

Response

Action payload

output : object of key-value pairs

Input of the action

Bot

Endpoints
POST
/v1/admin/bots
PUT
/v1/admin/bots/{id}
GET
/v1/admin/bots
GET
/v1/admin/bots/{id}
DELETE
/v1/admin/bots/{id}
GET
/v1/admin/bots/{id}/logs
GET
/v1/admin/bots/{id}/analytics
GET
/v1/admin/bots/{id}/issues
DELETE
/v1/admin/bots/{id}/issues/{issueId}
GET
/v1/admin/bots/{id}/issues/{issueId}/events

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

  • x-workspace-id: The ID of the workspace that the Bot belongs to.

The Bot object

Attributes

id : string

Id of the Bot

createdAt : string

Creation date of the Bot in ISO 8601 format

updatedAt : string

Updating date of the Bot in ISO 8601 format

signingSecret : string

Signing secret of the Bot

integrations : object of key-value pairs (16)

user : object (1)

conversation : object (1)

message : object (1)

states : object of key-value pairs (3)

configuration : object (2)

events : object of key-value pairs (3)

recurringEvents : object of key-value pairs (5)

subscriptions : object (1)

actions : object of key-value pairs (4)

name : string

Name of the Bot

deployedAt : string

Last deployment date of the Bot in the ISO 8601 format

dev : boolean

Indicates if the Bot is a development bot; Development bots run locally and can install dev integrations

createdBy : string

Id of the user that created the bot

alwaysAlive : boolean

Indicates if the Bot should be in always alive mode

status : string

Status of the bot

Possible values: active, deploying

medias : array of object

Media files associated with the Bot

url : string

URL of the media file

name : string

Name of the media file

Create Bot

POST
/v1/admin/bots

Create bot

Body

states : object of key-value pairs (3)

events : object of key-value pairs (3)

recurringEvents : object of key-value pairs (3)

subscriptions : object (1)

actions : object of key-value pairs (4)

configuration : object (2)

user : object (1)

conversation : object (1)

message : object (1)

code : string

JavaScript code of the bot

name : string

Optional name for the bot, if not provided will be auto-generated

medias : array of object

Media files associated with the Bot

url : string

name : string

url : string

URL of the Bot; Only available for dev bots

dev : boolean

Indicates if the Bot is a development bot; Development bots run locally and can install dev integrations

Response

Success

bot : object (21)

Update Bot

PUT
/v1/admin/bots/{id}

Update bot

Path

id : string

Bot ID

Body

url : string

URL of the Bot; Only available for dev bots

authentication : string

Type of the Bot authentication (iam)

Possible values: iam

configuration : object (2)

blocked : boolean

alwaysAlive : boolean

Indicates if the Bot should be in always alive mode

user : object (1)

message : object (1)

conversation : object (1)

events : object of key-value pairs (3)

actions : object of key-value pairs (4)

states : object of key-value pairs (3)

recurringEvents : object of key-value pairs (3)

integrations : object of key-value pairs (2)

subscriptions : object (1)

code : string

JavaScript code of the bot

name : string

Optional name for the bot, if not provided will be auto-generated

medias : array of object

Media files associated with the Bot

url : string

name : string

Response

Success

bot : object (21)

List Bots

GET
/v1/admin/bots

List bots

Query

dev : boolean

If true, only dev bots are returned. Otherwise, only production bots are returned.

nextToken : string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

sortField : string

Sort results by this field

sortDirection : string

Sort results in this direction

Response

Success

bots : array of object

id : string

Id of the Bot

createdAt : string

Creation date of the Bot in ISO 8601 format

updatedAt : string

Updating date of the Bot in ISO 8601 format

name : string

deployedAt : string

meta : object (1)

Get Bot

GET
/v1/admin/bots/{id}

Get bot details

Path

id : string

Bot ID

Response

Success

bot : object (21)

Delete Bot

DELETE
/v1/admin/bots/{id}

Delete bot

Path

id : string

Bot ID

Response

Success

Get Bot Logs

GET
/v1/admin/bots/{id}/logs

Get bot logs

Path

id : string

Bot ID

Query

timeStart : string

Beginning of the time range to get logs from

timeEnd : string

End of the time range to get logs from

nextToken : string

Token to get the next page of logs

Response

Success

logs : array of object

timestamp : string

level : string

message : string

nextToken : string

Get Bot Analytics

GET
/v1/admin/bots/{id}/analytics

Get bot analytics

Path

id : string

Bot ID

Query

startDate : string

Start date/time (inclusive)

endDate : string

End date/time (exclusive)

Response

Success

records : array of object

startDateTimeUtc : string

ISO 8601 date string of the beginning (inclusive) of the period

endDateTimeUtc : string

ISO 8601 date string of the end (exclusive) of the period

returningUsers : integer

newUsers : integer

sessions : integer

messages : integer

Deprecated. Use userMessages instead.

userMessages : integer

botMessages : integer

events : integer

eventTypes : object of key-value pairs

customEvents : object of key-value pairs

List Bot Issues

GET
/v1/admin/bots/{id}/issues

List Bot Issues

Path

id : string

Bot ID

Query

nextToken : string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

Response

Success

issues : array of object

id : string

code : string

createdAt : string

lastSeenAt : string

title : string

description : string

groupedData : object of key-value pairs (2)

eventsCount : number

category : string

Possible values: user_code, limits, configuration, other

resolutionLink : string

meta : object (1)

Delete Bot Issue

DELETE
/v1/admin/bots/{id}/issues/{issueId}

Delete Bot Issue

Path

id : string

Bot ID

issueId : string

Issue ID

Response

Success

List Bot Issue Events

GET
/v1/admin/bots/{id}/issues/{issueId}/events

List Events for a Bot Issue

Path

id : string

Bot ID

issueId : string

Issue ID

Response

Success

issueEvents : array of object

id : string

createdAt : string

data : object of key-value pairs (2)

Integration

Endpoints
POST
/v1/admin/integrations
PUT
/v1/admin/integrations/{id}
GET
/v1/admin/integrations
GET
/v1/admin/integrations/{id}
GET
/v1/admin/integrations/{name}/{version}
DELETE
/v1/admin/integrations/{id}

Required Headers

To access these API endpoints the following HTTP headers are required to be passed in all requests:

  • x-workspace-id: The ID of the workspace that the Integration belongs to.

The Integration object

Attributes

id : string

ID of the Integration

createdAt : string

Creation date of the Integration in ISO 8601 format

updatedAt : string

Updating date of the Integration in ISO 8601 format

identifier : object (2)

url : string

URL of the Integration

name : string

Name of the Integration

version : string

Version of the Integration

interfaces : object of key-value pairs (4)

configuration : object (2)

channels : object of key-value pairs (5)

states : object of key-value pairs (2)

events : object of key-value pairs (3)

actions : object of key-value pairs (4)

user : object (2)

entities : object of key-value pairs (3)

dev : boolean

Indicates if the integration is a development integration; Dev integrations run locally

title : string

Title of the integration. This is the name that will be displayed in the UI

description : string

Description of the integration. This is the description that will be displayed in the UI

iconUrl : string

URL of the icon of the integration. This is the icon that will be displayed in the UI

readmeUrl : string

URL of the readme of the integration. This is the readme that will be displayed in the UI

public : boolean

Idicates if the integration is public. Public integrations are available to all and cannot be updated without creating a new version.

secrets : array of string

Secrets are integration-wide values available in the code via environment variables formatted with a SECRET_ prefix followed by your secret name. A secret name must respect SCREAMING_SNAKE casing.

Create Integration

POST
/v1/admin/integrations

Create integration

Body

name : string

Name of the Integration

version : string

Version of the Integration

interfaces : object of key-value pairs (4)

configuration : object (2)

states : object of key-value pairs (2)

events : object of key-value pairs (3)

actions : object of key-value pairs (4)

entities : object of key-value pairs (3)

identifier : object (2)

channels : object of key-value pairs (5)

user : object (2)

secrets : object of key-value pairs

Secrets are integration-wide values available in the code via environment variables formatted with a SECRET_ prefix followed by your secret name. A secret name must respect SCREAMING_SNAKE casing.

code : string

JavaScript code of the integration

url : string

URL of the integration

dev : boolean

Indicates if the integration is a development integration; Dev integrations run locally

icon : string

Base64 encoded svg of the integration icon. This icon is global to the integration each versions will be updated when this changes.

readme : string

Base64 encoded markdown of the integration readme. The readme is specific to each integration versions.

title : string

Title of the integration. This is the name that will be displayed in the UI

description : string

Description of the integration. This is the description that will be displayed in the UI

public : boolean

Idicates if the integration is public. Public integrations are available to all and cannot be updated without creating a new version.

Response

Success

integration : object (22)

Update Integration

PUT
/v1/admin/integrations/{id}

Update integration

Path

id : string

Integration ID

Body

configuration : object (2)

channels : object of key-value pairs (5)

identifier : object (2)

actions : object of key-value pairs (4)

events : object of key-value pairs (3)

states : object of key-value pairs (2)

user : object (2)

entities : object of key-value pairs (3)

interfaces : object of key-value pairs (4)

secrets : object of key-value pairs

Secrets are integration-wide values available in the code via environment variables formatted with a SECRET_ prefix followed by your secret name. A secret name must respect SCREAMING_SNAKE casing.

code : string

JavaScript code of the integration

icon : string

Base64 encoded svg of the integration icon. This icon is global to the integration each versions will be updated when this changes.

readme : string

Base64 encoded markdown of the integration readme. The readme is specific to each integration versions.

title : string

Title of the integration. This is the name that will be displayed in the UI

description : string

Description of the integration. This is the description that will be displayed in the UI

url : string

URL of the integration

public : boolean

Idicates if the integration is public. Public integrations are available to all and cannot be updated without creating a new version.

Response

Success

integration : object (22)

List Integrations

GET
/v1/admin/integrations

List integrations

Query

nextToken : string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

name : string

Integration Name

version : string

Integration version. Either a semver version or tag "latest"

dev : boolean

If true, only dev integrations are returned. Otherwise, only production integrations are returned.

Response

Success

integrations : array of object

id : string

ID of the Integration

name : string

Name of the Integration

version : string

Version of the Integration

createdAt : string

Creation date of the Integration in ISO 8601 format

updatedAt : string

Updating date of the Integration in ISO 8601 format

title : string

Title of the integration. This is the name that will be displayed in the UI

description : string

Description of the integration. This is the description that will be displayed in the UI

iconUrl : string

URL of the icon of the integration. This is the icon that will be displayed in the UI

public : boolean

Idicates if the integration is public. Public integrations are available to all and cannot be updated without creating a new version.

meta : object (1)

Get Integration

GET
/v1/admin/integrations/{id}

Get integration

Path

id : string

Integration ID

Response

Success

integration : object (22)

Get Integration By Name

GET
/v1/admin/integrations/{name}/{version}

Get integration

Path

name : string

Integration Name

version : string

Integration version. Either a semver version or tag "latest"

Response

Success

integration : object (22)

Delete Integration

DELETE
/v1/admin/integrations/{id}

Delete integration

Path

id : string

Integration ID

Response

Success

Tables

Manage and interact with table structures, including creation, updates, and querying of tables and their rows.

Endpoints
GET
/v1/tables
GET
/v1/tables/{table}
POST
/v1/tables/{table}
POST
/v1/tables
POST
/v1/tables/{sourceTableId}/duplicate
PUT
/v1/tables/{table}
PUT
/v1/tables/{table}/column
DELETE
/v1/tables/{table}
GET
/v1/tables/{table}/row
POST
/v1/tables/{table}/rows/find
POST
/v1/tables/{table}/rows
POST
/v1/tables/{table}/rows/delete
PUT
/v1/tables/{table}/rows
POST
/v1/tables/{table}/rows/upsert

The Table object

Attributes

id : string

Unique identifier for the table

name : string

Required. This name is used to identify your table.

factor : number

The 'factor' multiplies the row's data storage limit by 4KB and its quota count, but can only be set at table creation and not modified later. For instance, a factor of 2 increases storage to 8KB but counts as 2 rows in your quota. The default factor is 1.

frozen : boolean

A table designated as "frozen" is immutable in terms of its name and schema structure; modifications to its schema or a renaming operation are not permitted. The only action that can be taken on such a table is deletion. The schema established at the time of creation is locked in as the final structure. To implement any changes, the table must be duplicated with the desired alterations.

schema : object (5)

tags : object of key-value pairs

Optional tags to help organize your tables. These should be passed here as an object representing key/value pairs.

isComputeEnabled : boolean

Indicates if the table is enabled for computation.

createdAt : string

Timestamp of table creation.

updatedAt : string

Timestamp of the last table update.

List Tables

GET
/v1/tables

Retrieves a list of all tables associated with your bot.

Query

tags : object

Optional filters to narrow down the list by tags associated with tables.

Response

Returns a list of tables.

tables : array of object

id : string

Unique identifier for the table

name : string

Required. This name is used to identify your table.

factor : number

The 'factor' multiplies the row's data storage limit by 4KB and its quota count, but can only be set at table creation and not modified later. For instance, a factor of 2 increases storage to 8KB but counts as 2 rows in your quota. The default factor is 1.

frozen : boolean

A table designated as "frozen" is immutable in terms of its name and schema structure; modifications to its schema or a renaming operation are not permitted. The only action that can be taken on such a table is deletion. The schema established at the time of creation is locked in as the final structure. To implement any changes, the table must be duplicated with the desired alterations.

schema : object (5)

tags : object of key-value pairs

Optional tags to help organize your tables. These should be passed here as an object representing key/value pairs.

isComputeEnabled : boolean

Indicates if the table is enabled for computation.

createdAt : string

Timestamp of table creation.

updatedAt : string

Timestamp of the last table update.

Get Table

GET
/v1/tables/{table}

Retrieves detailed information about a specific table, identified by its name or unique identifier.

Path

table : string

The table's name or unique identifier for targeting specific table operations.

Response

Details of the requested table, including row count and indexing status.

table : object (9)

rows : number

The total number of rows present in the table.

stale : number

The number of stale rows that are waiting to be processed

indexing : number

The number of rows that are waiting to be indexed (for search)

Get Or Create Table

POST
/v1/tables/{table}

Retrieves information about a specific table if it exists; otherwise, creates a new table based on the provided schema.

Path

table : string

The table's name or unique identifier for targeting specific table operations.

Body

factor : number

The 'factor' multiplies the row's data storage limit by 4KB and its quota count, but can only be set at table creation and not modified later. For instance, a factor of 2 increases storage to 8KB but counts as 2 rows in your quota. The default factor is 1.

frozen : boolean

A table designated as "frozen" is immutable in terms of its name and schema structure; modifications to its schema or a renaming operation are not permitted. The only action that can be taken on such a table is deletion. The schema established at the time of creation is locked in as the final structure. To implement any changes, the table must be duplicated with the desired alterations.

schema : object of key-value pairs

Provide an object or a JSON schema to define the columns of the table. A maximum of 20 keys in the object/schema is allowed.

tags : object of key-value pairs

Optional tags to help organize your tables. These should be passed here as an object representing key/value pairs.

isComputeEnabled : boolean

Indicates if the table is enabled for computation.

Response

The retrieved or created table object.

table : object (9)

created : boolean

Flag indicating if the table was newly created.

rows : number

The total number of rows present in the table.

stale : number

The number of stale rows that are waiting to be processed

indexing : number

The number of rows that are waiting to be indexed (for search)

Create Table

POST
/v1/tables

Initiates the creation of a new table based on the provided schema, excluding system-managed fields like IDs and timestamps.

Body

name : string

Required. This name is used to identify your table.

factor : number

The 'factor' multiplies the row's data storage limit by 4KB and its quota count, but can only be set at table creation and not modified later. For instance, a factor of 2 increases storage to 8KB but counts as 2 rows in your quota. The default factor is 1.

frozen : boolean

A table designated as "frozen" is immutable in terms of its name and schema structure; modifications to its schema or a renaming operation are not permitted. The only action that can be taken on such a table is deletion. The schema established at the time of creation is locked in as the final structure. To implement any changes, the table must be duplicated with the desired alterations.

schema : object of key-value pairs

Provide an object or a JSON schema to define the columns of the table. A maximum of 20 keys in the object/schema is allowed.

tags : object of key-value pairs

Optional tags to help organize your tables. These should be passed here as an object representing key/value pairs.

isComputeEnabled : boolean

Indicates if the table is enabled for computation.

Response

The created table object.

table : object (9)

Duplicate Table

POST
/v1/tables/{sourceTableId}/duplicate

Duplicates the table schema & content

Path

sourceTableId : string

The table's unique identifier

Body

tableName : string

schemaOnly : boolean

Only duplicate the schema, not the content

factor : number

Use a different factor for the table. Leave empty to use the same as the duplicated table.

Response

The created table object.

table : object (9)

rows : number

The total number of rows present in the table.

Update Table

PUT
/v1/tables/{table}

Updates the schema or the name of an existing table.

Path

table : string

The table's name or unique identifier for targeting specific table operations.

Body

name : string

Required. This name is used to identify your table.

frozen : boolean

A table designated as "frozen" is immutable in terms of its name and schema structure; modifications to its schema or a renaming operation are not permitted. The only action that can be taken on such a table is deletion. The schema established at the time of creation is locked in as the final structure. To implement any changes, the table must be duplicated with the desired alterations.

schema : object of key-value pairs

Provide an object or a JSON schema to define the columns of the table. A maximum of 20 keys in the object/schema is allowed.

tags : object of key-value pairs

Optional tags to help organize your tables. These should be passed here as an object representing key/value pairs.

isComputeEnabled : boolean

Indicates if the table is enabled for computation.

Response

The updated table

table : object (9)

staleColumns : array of string

List of columns that have become stale following the modification.

Rename Table Column

PUT
/v1/tables/{table}/column

Renames an existing column within a table to better reflect its content or usage. The operation targets a specific table and requires the current and new column names.

Path

table : string

The table's name or unique identifier for targeting specific table operations.

Body

name : string

The existing name of the column.

newName : string

The new name to assign to the column.

Response

Confirmation of the column rename operation, including the updated table schema.

table : object (9)

Delete Table

DELETE
/v1/tables/{table}

Permanently deletes a table and all its associated data from the system. Use with caution, as this action cannot be undone.

Path

table : string

The table's name or unique identifier for targeting specific table operations.

Response

Confirmation that the table has been deleted.

Get Table Row

GET
/v1/tables/{table}/row

Fetches a specific row from a table using the row's unique identifier.

Path

table : string

The table's name or unique identifier for targeting specific table operations.

Query

id : integer

Identifier of the row within the table.

Response

The requested row object.

row : object of key-value pairs (6)

Find Table Rows

POST
/v1/tables/{table}/rows/find

Enables the search and filtering of rows within a table based on specific criteria. This operation supports complex queries for advanced data manipulation and retrieval.

Path

table : string

The table's name or unique identifier for targeting specific table operations.

Body

limit : integer

Limit for pagination, specifying the maximum number of rows to return.

offset : integer

Offset for pagination, specifying where to start returning rows from.

filter : object of key-value pairs

Provide a mongodb-like filter to apply to the query. Example: { "name": { "$eq": "John" } }

group : object of key-value pairs

Group the rows by a specific column and apply aggregations to them. Allowed values: key, avg, max, min, sum, count. Example: { "someId": "key", "orders": ["sum", "avg"] }

search : string

Search term to apply to the row search. When using this parameter, some rows which doesn't match the search term will be returned, use the similarity field to know how much the row matches the search term.

orderBy : string

Specifies the column by which to order the results. By default it is ordered by id. Build-in columns: id, createdAt, updatedAt

orderDirection : string

Specifies the direction of sorting, either ascending or descending.

Possible values: asc, desc

Response

A collection of rows that match the search criteria, along with metadata such as total count and pagination details.

rows : array of object

id : number

Unique identifier for the row.

createdAt : string

Timestamp of row creation.

updatedAt : string

Timestamp of the last row update.

computed : object of key-value pairs (4)

stale : array of string

[Read-only] List of stale values that are waiting to be recomputed.

similarity : number

Optional numeric value indicating similarity, when using findTableRows.

hasMore : boolean

Flag indicating if there are more rows to fetch.

offset : integer

limit : integer

warnings : array of string

Alerts for minor issues that don't block the operation but suggest possible improvements.

Create Table Rows

POST
/v1/tables/{table}/rows

Inserts one or multiple new rows into the specified table.

Path

table : string

The table's name or unique identifier for targeting specific table operations.

Body

rows : array of object

waitComputed : boolean

Ensure computed columns are fully processed before returning the result. This is applicable only when the number of rows involved is fewer than 1.

Response

A summary of the insertion operation, including any warnings or errors encountered, and the inserted row data.

rows : array of object

id : number

Unique identifier for the row.

createdAt : string

Timestamp of row creation.

updatedAt : string

Timestamp of the last row update.

computed : object of key-value pairs (4)

stale : array of string

[Read-only] List of stale values that are waiting to be recomputed.

similarity : number

Optional numeric value indicating similarity, when using findTableRows.

warnings : array of string

Alerts for minor issues that don't block the operation but suggest possible improvements.

errors : array of string

Critical issues in specific elements that prevent their successful processing, allowing partial operation success.

Delete Table Rows

POST
/v1/tables/{table}/rows/delete

Allows selective deletion of rows or complete clearance of a table.

Path

table : string

The table's name or unique identifier for targeting specific table operations.

Body

ids : array of number

filter : object of key-value pairs

Filter to apply when deleting rows. Example: { "name": { "$eq": "John" } }

deleteAllRows : boolean

Flag to delete all rows. Use with caution as this action is irreversible.

Response

Confirms the number of rows successfully deleted.

deletedRows : number

Update Table Rows

PUT
/v1/tables/{table}/rows

Updates specified rows in a table, allowing partial success with detailed feedback on errors.

Path

table : string

The table's name or unique identifier for targeting specific table operations.

Body

rows : array of object

Rows with updated data, identified by ID.

id : number

waitComputed : boolean

Ensure computed columns are fully processed before returning the result. This is applicable only when the number of rows involved is fewer than 1.

Response

Returns updated rows, including warnings for minor issues and errors for failed updates.

rows : array of object

id : number

Unique identifier for the row.

createdAt : string

Timestamp of row creation.

updatedAt : string

Timestamp of the last row update.

computed : object of key-value pairs (4)

stale : array of string

[Read-only] List of stale values that are waiting to be recomputed.

similarity : number

Optional numeric value indicating similarity, when using findTableRows.

warnings : array of string

Alerts for minor issues that don't block the operation but suggest possible improvements.

errors : array of string

Critical issues in specific elements that prevent their successful processing, allowing partial operation success.

Upsert Table Rows

POST
/v1/tables/{table}/rows/upsert

Inserts or updates rows based on a key. If a row exists, it is updated; otherwise, a new row is created.

Path

table : string

The table's name or unique identifier for targeting specific table operations.

Body

rows : array of object

id : number

keyColumn : string

Determines if a row is inserted or updated. Defaults to "id".

waitComputed : boolean

Ensure computed columns are fully processed before returning the result. This is applicable only when the number of rows involved is fewer than 1.

Response

Summary of insertions and updates, including any warnings or errors.

inserted : array of object

id : number

Unique identifier for the row.

createdAt : string

Timestamp of row creation.

updatedAt : string

Timestamp of the last row update.

computed : object of key-value pairs (4)

stale : array of string

[Read-only] List of stale values that are waiting to be recomputed.

similarity : number

Optional numeric value indicating similarity, when using findTableRows.

updated : array of object

id : number

Unique identifier for the row.

createdAt : string

Timestamp of row creation.

updatedAt : string

Timestamp of the last row update.

computed : object of key-value pairs (4)

stale : array of string

[Read-only] List of stale values that are waiting to be recomputed.

similarity : number

Optional numeric value indicating similarity, when using findTableRows.

warnings : array of string

Alerts for minor issues that don't block the operation but suggest possible improvements.

errors : array of string

Critical issues in specific elements that prevent their successful processing, allowing partial operation success.

Files

The Files API allows you to create, manage, and index files that can be used by your bots and integrations. Files can be in any text or binary format, and documents (such as PDF, Microsoft Office, HTML, CSV, etc.) can be indexed to be used for semantic search in RAG (Retrieval Augmented Generation) implementations. Files are private by default but can be made publicly accessible through a permanent URL that's unique for each file.

Endpoints
PUT
/v1/files
DELETE
/v1/files/{id}
GET
/v1/files
GET
/v1/files/{id}
PUT
/v1/files/{id}
GET
/v1/files/search

The File object

Attributes

id : string

File ID

botId : string

The ID of the bot the file belongs to

key : string

Unique key for the file. Must be unique across the bot (and the integration, when applicable).

url : string

URL to retrieve the file content. This URL will be ready to use once the file is uploaded.

If the file has a public_content policy, this will contain the permanent public URL to retrieve the file, otherwise this will contain a temporary pre-signed URL to download the file which should be used shortly after retrieving and should not be stored long-term as the URL will expire after a short timeframe.

size : number

File size in bytes. Non-null if file upload status is "COMPLETE".

contentType : string

MIME type of the file's content

tags : object of key-value pairs

The tags of the file as an object of key/value pairs

createdAt : string

File creation timestamp in ISO 8601 format

updatedAt : string

File last update timestamp in ISO 8601 format

accessPolicies : array of string

Access policies configured for the file.

Possible values for array items: integrations, public_content

index : boolean

Whether the file was requested to be indexed for search or not.

status : string

Status of the file. If the status is upload_pending, the file content has not been uploaded yet. The status will be set to upload_completed once the file content has been uploaded successfully.

If the upload failed for any reason (e.g. exceeding the storage quota or the maximum file size limit) the status will be set to upload_failed and the reason for the failure will be available in the failedStatusReason field of the file.

However, if the file has been uploaded and the index attribute was set to true on the file, the status will immediately transition to the indexing_pending status (the upload_completed status step will be skipped).

Once the indexing is completed and the file is ready to be used for searching its status will be set to indexing_completed. If the indexing failed the status will be set to indexing_failed and the reason for the failure will be available in the failedStatusReason field.

Possible values: upload_pending, upload_failed, upload_completed, indexing_pending, indexing_failed, indexing_completed

failedStatusReason : string

If the file status is upload_failed or indexing_failed this will contain the reason of the failure.

Upsert File

PUT
/v1/files

Creates or updates a file using the key parameter as unique identifier. Updating a file will erase the existing content of the file. Upload the file content by sending it in a PUT request to the uploadUrl returned in the response.

Body

key : string

Unique key for the file. Must be unique across the bot (and the integration, when applicable).

tags : object of key-value pairs

File tags as an object of key-value pairs. Tag values should be of string (text) type.

size : number

File size in bytes. This will count against your File Storage quota. If the index parameter is set to true, this will also count against your Vector DB Storage quota.

index : boolean

Set to a value of 'true' to index the file in vector storage. Only PDFs, Office documents, and text-based files are currently supported. Note that if a file is indexed, it will count towards both the Vector DB Storage quota and the File Storage quota of the workspace.

accessPolicies : array of string

File access policies. Add "public_content" to allow public access to the file content. Add "integrations" to allow read, search and list operations for any integration installed in the bot.

Possible values for array items: public_content, integrations

contentType : string

File content type. If omitted, the content type will be inferred from the file extension (if any) specified in key. If a content type cannot be inferred, the default is "application/octet-stream".

Response

The created or updated file

file : object (14)

Delete File

DELETE
/v1/files/{id}

Deletes a file.

Path

id : string

File ID

Response

Empty response.

List Files

GET
/v1/files

List files for bot

Query

nextToken : string

Provide the meta.nextToken value provided in the last API response to retrieve the next page of results

tags : object

Filter files by tags. Tags should be passed as a URL-encoded JSON object of key-value pairs that must be present in the tags of a file.

Response

Returns the list of files related to the bot.

files : array of object

id : string

File ID

botId : string

The ID of the bot the file belongs to

key : string

Unique key for the file. Must be unique across the bot (and the integration, when applicable).

url : string

URL to retrieve the file content. This URL will be ready to use once the file is uploaded.

If the file has a public_content policy, this will contain the permanent public URL to retrieve the file, otherwise this will contain a temporary pre-signed URL to download the file which should be used shortly after retrieving and should not be stored long-term as the URL will expire after a short timeframe.

size : number

File size in bytes. Non-null if file upload status is "COMPLETE".

contentType : string

MIME type of the file's content

tags : object of key-value pairs

The tags of the file as an object of key/value pairs

createdAt : string

File creation timestamp in ISO 8601 format

updatedAt : string

File last update timestamp in ISO 8601 format

accessPolicies : array of string

Access policies configured for the file.

Possible values for array items: integrations, public_content

index : boolean

Whether the file was requested to be indexed for search or not.

status : string

Status of the file. If the status is upload_pending, the file content has not been uploaded yet. The status will be set to upload_completed once the file content has been uploaded successfully.

If the upload failed for any reason (e.g. exceeding the storage quota or the maximum file size limit) the status will be set to upload_failed and the reason for the failure will be available in the failedStatusReason field of the file.

However, if the file has been uploaded and the index attribute was set to true on the file, the status will immediately transition to the indexing_pending status (the upload_completed status step will be skipped).

Once the indexing is completed and the file is ready to be used for searching its status will be set to indexing_completed. If the indexing failed the status will be set to indexing_failed and the reason for the failure will be available in the failedStatusReason field.

Possible values: upload_pending, upload_failed, upload_completed, indexing_pending, indexing_failed, indexing_completed

failedStatusReason : string

If the file status is upload_failed or indexing_failed this will contain the reason of the failure.

meta : object (1)

Get File

GET
/v1/files/{id}

Get file

Path

id : string

File ID

Response

An object containing the file metadata and URL

file : object (13)

Update File Metadata

PUT
/v1/files/{id}

Update file metadata, without updating the file content.

Path

id : string

File ID

Body

tags : object of key-value pairs

The file tags to update as an object of key-value pairs with string (text) values. Omit to keep existing tags intact. Any existing tags not included will be preserved. New tags will be added. To delete a tag, set its value to null.

accessPolicies : array of string

New access policies to set for the file. Omit to keep existing policies intact.

Possible values for array items: integrations, public_content

Response

An object containing the updated file metadata.

file : object (13)

Search Files

GET
/v1/files/search

Search files

Query

tags : object

Filter files by tags. Tags should be passed as a URL-encoded JSON object of key-value pairs that must be present in the tags of a file.

query : string

Query expressed in natural language to retrieve matching text passages within all indexed files in the bot using semantical search.

contextDepth : integer

The number of neighbor passages to prepend and append as surrounding context to the content of each returned passage. Default: 0, Maximum: 10

limit : integer

The maximum number of passages to return.

Response

Returns the text passages within all indexed files that matched the query.

passages : array of object

content : string

The content of the matching passage in the file including surrounding context, if any.

score : number

The score indicating the similarity of the passage to the query. A higher score indicates higher similarity.

meta : object (3)

file : object (4)