API

Version: 1.0.0

This API facilitates the management of agents, chats, messages, and workflows within the Brightsy AI ecosystem, providing endpoints for creating, retrieving, updating, and deleting resources.

Base URL

https://brightsy.ai/api/v1beta

Authentication

The API uses bearer token authentication to secure its endpoints.

Type: HTTP Bearer Authentication
Format: Include your API key in the Authorization header

Authorization: Bearer YOUR_API_KEY

Timeouts

All API endpoints have a required timeout of 300 seconds. Clients should be configured to wait at least 300 seconds for a response before timing out the request. This is especially important for endpoints that perform complex processing or generate completions.

Endpoints

Agents

Attachments

Delete an Attachment

DELETE /agents/{agentId}/chat/completion/workspace/{chatId}/messages/{messageId}/attachments/{filename}

Deletes a specific attachment from a message.

Path Parameters:

• agentId - The unique identifier of the agent (string, required)
• chatId - The unique identifier of the chat (string, required)
• messageId - The unique identifier of the message (string, required)
• filename - The name of the file to delete (string, required)

Responses:

• 200 OK - File deleted successfully
• 204 No Content - For CORS preflight requests

Upload an Attachment

POST /agent/{agentId}/chat/completion/workspace/{chatId}/message/{messageId}/attachment

Uploads an attachment to a message.

Path Parameters:

• agentId - The unique identifier of the agent (string, required)
• chatId - The unique identifier of the chat (string, required)
• messageId - The unique identifier of the message (string, required)

Request Body:

• Content Type: multipart/form-data
• Schema: An object containing a file property of type binary

Responses:

• 200 OK - File uploaded successfully
• 204 No Content - For CORS preflight requests

Messages

Create or Update Message

POST /agent/{agentId}/chat/completion/workspace/{chatId}/message/{messageId}

Creates or updates a message within a chat.

Path Parameters:

• agentId - The unique identifier of the agent (string, required)
• chatId - The unique identifier of the chat (string, required)
• messageId - The unique identifier of the message (string, required)

Request Body:

• Content Type: application/json
• Schema: A Message object

Responses:

• 200 OK - Message created/updated successfully

Delete Message

DELETE /agent/{agentId}/chat/completion/workspace/{chatId}/message/{messageId}

Deletes a specific message.

Path Parameters:

• agentId - The unique identifier of the agent (string, required)
• chatId - The unique identifier of the chat (string, required)
• messageId - The unique identifier of the message (string, required)

Responses:

• 200 OK - Message deleted successfully
• 204 No Content - For CORS preflight requests

List Messages

GET /agent/{agentId}/chat/completion/workspace/{chatId}/message

Retrieves a list of messages within a chat.

Path Parameters:

• agentId - The unique identifier of the agent (string, required)
• chatId - The unique identifier of the chat (string, required)

Responses:

• 200 OK - Returns a list of messages

Add Message to Chat

POST /agent/{agentId}/chat/completion/workspace/{chatId}/message

Creates a new message within a chat.

Path Parameters:

• agentId - The unique identifier of the agent (string, required)
• chatId - The unique identifier of the chat (string, required)

Request Body:

• Content Type: application/json
• Schema: A Message object

Responses:

• 200 OK - Message created successfully
• 204 No Content - For CORS preflight requests

Chats

Get Chat Details

GET /agent/{agentId}/chat/completion/workspace/{chatId}/message

Retrieves details of a specific chat.

Path Parameters:

• agentId - The unique identifier of the agent (string, required)
• chatId - The unique identifier of the chat (string, required)

Responses:

• 200 OK - Returns chat details

Create Chat

POST /agent/{agentId}/chat/completion/workspace/{chatId}/message

Creates a new message and chat if needed.

Path Parameters:

• agentId - The unique identifier of the agent (string, required)
• chatId - The unique identifier of the chat (string, required)

Request Body:

• Content Type: application/json
• Schema: An object containing a message property of type string

Responses:

• 200 OK - Chat created successfully
• 204 No Content - For CORS preflight requests

Agent Messages

Create Workspace Chat

POST /agent/{agentId}/chat/completion/workspace

Creates a message for an agent and starts a new workspace-based chat.

Path Parameters:

• agentId - The unique identifier of the agent (string, required)

Request Body:

• Content Type: application/json
• Schema: A Message object

Responses:

• 200 OK - Message created successfully
• 204 No Content - For CORS preflight requests

Create Completion

POST /agents/{agentId}/chat/completion

Creates a completion where the client provides the entire messages array.

Path Parameters:

• agentId - The unique identifier of the agent (string, required)

Request Body:

• Content Type: application/json
• Schema: An object containing a messages array with the complete conversation history

Responses:

• 200 OK - Completion generated successfully
• 204 No Content - For CORS preflight requests

Note: This endpoint does not store the conversation in Brightsy. No chatId is used as the conversation is managed by the client.

Scenarios

Execute Scenario

POST /scenario/{scenarioId}

Executes a scenario.

Path Parameters:

• scenarioId - The unique identifier of the scenario (string, required)

Request Headers:

• [Signature Header Name] - The header name is defined in the scenario configuration as signature_name. For example, if signature_name is set to "X-Scenario-Signature", you would include that header in your request. While you could technically use the raw signature_secret as the header value, it's best practice to generate a signature using the signature_secret and the payload as described below.

Signature Generation:

The signature must be generated using HMAC SHA-256 with the following process:

1. Convert the entire request body to a JSON string (payload)
2. Create an HMAC SHA-256 hash using the scenario's signature_secret as the key
3. Update the hash with the payload string directly
4. Get the hex digest of the hash, which becomes the signature value

Example (Node.js):

const crypto = require('crypto');
const payload = JSON.stringify(requestBody);
const signature = crypto.createHmac('sha256', signature_secret)
  .update(payload, 'utf8')
  .digest('hex');

Security Best Practice: Using HMAC signatures as shown above is the recommended best practice for API security. The signature validates the authenticity of requests and ensures data integrity, protecting against tampering. Store your signature_secret securely and never expose it in client-side code.

Request Body:

• Content Type: application/json
• Schema: An object containing an input property of type string

Responses:

• 200 OK - Scenario executed successfully
• 401 Unauthorized - When the signature header is missing or invalid
• 204 No Content - For CORS preflight requests

Object Models

Message Object

Represents a message with various content types.

Properties:

• id - Unique identifier for the message (string)
• content - Array of content items, each being one of:
  • Text: Object with type as "text" and text as a string
  • Image URL: Object with type as "image_url" and image_url containing url and optional detail

Example:

{
  "id": "msg_123456789",
  "content": [
    {
      "type": "text",
      "text": "Hello, this is a text message"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.jpg",
        "detail": "high"
      }
    }
  ]
}

Chat Object

Represents a chat containing messages.

Properties:

• id - Unique identifier for the chat (string)
• messages - Array of Message objects

Example:

{
  "id": "chat_987654321",
  "messages": [
    {
      "id": "msg_123456789",
      "content": [
        {
          "type": "text",
          "text": "Hello, this is a text message"
        }
      ]
    }
  ]
}