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
}

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 Conversation

createdAt : string

Creation date of the User in ISO 8601 format

updatedAt : string

Updating date of the User in ISO 8601 format

tags : map of objects

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 : map of objects

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

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

conversationId : string

tags : object

Response

Returns a list of User objects

users : array of object

id : string

ID of the Conversation

createdAt : string

Creation date of the User in ISO 8601 format

updatedAt : string

Updating date of the User in ISO 8601 format

tags : map of objects

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 : map of objects

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

Body

tags : map of objects

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

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 : map of objects

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

Unique identifier of the integration that was installed on the bot

tags : map of objects

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

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

tags : object

participantIds : array of string

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 : map of objects

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

Unique identifier of the integration that was installed on the bot

tags : map of objects

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

Body

currentTaskId : string

tags : map of objects

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

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

Path

id : string

Response

Returns a list of Participant objects

participants : array of object

id : string

ID of the Conversation

createdAt : string

Creation date of the User in ISO 8601 format

updatedAt : string

Updating date of the User in ISO 8601 format

tags : map of objects

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

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

userId : string

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

userId : string

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 Conversation

createdAt : string

Creation date of the Event in ISO 8601 format

type : string

Type of the task

payload : map of objects

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

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

Unique identifier of the integration that was installed on the bot

payload : map of objects

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

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

type : string

conversationId : string

userId : string

messageId : string

status : string

Response

Returns a list of Event objects

events : array of object

id : string

ID of the Conversation

createdAt : string

Creation date of the Event in ISO 8601 format

type : string

Type of the task

payload : map of objects

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

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 Conversation

createdAt : string

Creation date of the Message in ISO 8601 format

type : string

Type of the task

payload : map of objects

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).

userId : string

ID of the Conversation

conversationId : string

ID of the Conversation

tags : map of objects

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 : map of objects

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

userId : string

User id

conversationId : string

User id

type : string

Unique identifier of the integration that was installed on the bot

tags : map of objects

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 : map of objects

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

userId : string

User id

conversationId : string

User id

type : string

Unique identifier of the integration that was installed on the bot

tags : map of objects

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

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

Body

tags : map of objects

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 Messages 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

conversationId : string

tags : object

Response

Returns a list of Messages objects.

messages : array of object

id : string

ID of the Conversation

createdAt : string

Creation date of the Message in ISO 8601 format

type : string

Type of the task

payload : map of objects

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).

userId : string

ID of the Conversation

conversationId : string

ID of the Conversation

tags : map of objects

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

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 Conversation

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 Conversation

conversationId : string

Id of the Conversation

userId : string

Id of the User

name : string

Type of the task

type : string

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

payload : map of objects

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

id : string

name : string

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

id : string

name : string

Body

payload : map of objects

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

id : string

name : string

Body

payload : map of objects

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

id : string

name : string

Body

payload : map of objects

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)

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

Unique identifier of the integration that was installed on the bot

input : map of objects

Input of the action

Response

Action payload

output : map of objects

Input of the action

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 : map of objects

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

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

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 : map of objects

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

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

Response

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

table : object (8)

rows : number

The total number of rows present in the table.

indexingCount : number

The number of rows pending indexing, relevant for search functionalities.

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

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 : map of objects

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 : map of objects

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

Response

The retrieved or created table object.

table : object (8)

created : boolean

Flag indicating if the table was newly created.

rows : number

The total number of rows present in the table.

indexingCount : number

The number of rows pending indexing, relevant for search functionalities.

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 : map of objects

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 : map of objects

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

Response

The created table object.

table : object (8)

Duplicate Table

POST
/v1/tables/{sourceTableId}/duplicate

Duplicates the table schema & content

Path

sourceTableId : string

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 (8)

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

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 : map of objects

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 : map of objects

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

Response

The updated table

table : object (8)

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

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 (8)

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

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

Query

id : integer

Response

The requested row object.

row : map of objects (4)

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

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 : map of objects

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

group : map of objects

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.

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.

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

Body

rows : array of object

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.

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

Body

ids : array of number

filter : map of objects

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

Body

rows : array of object

Rows with updated data, identified by ID.

id : number

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.

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

Body

rows : array of object

id : number

keyColumn : string

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

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.

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.

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.