API Reference

The Connect platform provides a RESTful API that allows you to manage agents, knowledge bases, and integrate AI capabilities into your applications.

Authentication

Most API requests require authentication using a JWT token obtained through the authentication process.

curl -X GET "https://api.example.com/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Public agent endpoints can be accessed without authentication.

Base URL

The base URL depends on your deployment configuration. By default, it's defined in your environment settings.

Endpoints

Agents

Create Agent

Create a new agent with optional knowledge base and integrations.

Endpoint: POST /agents

Authentication: Required

Request Format: multipart/form-data

Request Parameters:

Parameter	Type	Required	Description
`name`	string	Yes	Name of the agent
`systemPrompt`	string	No	System instructions for the agent
`logo`	file	No	Agent logo image file
`customCss`	file	No	CSS file for styling the agent interface
`integrationIds`	JSON string	No	Array of integration IDs to enable
`aiProvider`	string	No	Provider for the AI model
`enableRephrasing`	boolean	No	Whether to enable response rephrasing
`rephrasingProvider`	string	No	Provider for rephrasing service
`enableGuardrailing`	boolean	No	Whether to enable input guardrailing
`guardrailingProvider`	string	No	Provider for guardrailing service
`guardrailingRules`	string	No	Rules for guardrailing
`embeddingProvider`	string	No	Provider for embedding service
`chunkingStrategy`	string	No	Strategy for chunking knowledge documents

Response:

{
  "id": "agent_12345",
  "name": "Support Agent",
  "systemPrompt": "You are a helpful assistant...",
  "logo": "data:image/png;base64,...",
  "customCss": "/* Custom styles */",
  "published": false,
  "aiProvider": "openai",
  "enableRephrasing": false,
  "enableGuardrailing": false,
  "embeddingProvider": "openai",
  "chunkingStrategy": "semantic",
  "installedIntegrations": [],
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}

Get All Agents

Retrieve all agents owned by the authenticated user.

Endpoint: GET /agents

Authentication: Required

Response:

[
  {
    "id": "agent_12345",
    "name": "Support Agent",
    "systemPrompt": "You are a helpful assistant...",
    "published": false,
    "installedIntegrations": [],
    "createdAt": "2023-01-01T00:00:00.000Z",
    "updatedAt": "2023-01-01T00:00:00.000Z"
  }
]

Get Agent

Retrieve a specific agent by ID.

Endpoint: GET /agents/:id

Authentication: Required

Response: Same as Create Agent

Get Public Agent

Retrieve a published agent by ID, accessible without authentication.

Endpoint: GET /agents/public/:id

Authentication: Not required

Response: Limited agent information for public access

Update Agent

Update an existing agent.

Endpoint: PUT /agents/:id

Authentication: Required

Request Format: multipart/form-data

Request Parameters: Same as Create Agent

Response: Updated agent object

Delete Agent

Delete an agent.

Endpoint: DELETE /agents/:id

Authentication: Required

Response: Status 204 No Content

Knowledge Base

Upload Document

Upload a document to an agent's knowledge base.

Endpoint: POST /knowledge/:agentId/upload

Authentication: Required

Request Format: multipart/form-data

Request Parameters:

Parameter	Type	Required	Description
`file`	file	Yes	Document file (max 150KB)

Response:

{
  "id": 123,
  "fileName": "document.pdf",
  "fileType": "application/pdf",
  "metadata": {
    "size": 125000,
    "mimeType": "application/pdf",
    "uploadedAt": "2023-01-01T00:00:00.000Z",
    "uploadedBy": 456
  },
  "processing_status": "pending",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}

Get Knowledge Base

Retrieve all documents in an agent's knowledge base.

Endpoint: GET /knowledge/:agentId

Authentication: Required

Response:

[
  {
    "id": 123,
    "fileName": "document.pdf",
    "fileType": "application/pdf",
    "metadata": {
      "size": 125000,
      "mimeType": "application/pdf", 
      "uploadedAt": "2023-01-01T00:00:00.000Z",
      "uploadedBy": 456
    },
    "processing_status": "completed",
    "createdAt": "2023-01-01T00:00:00.000Z",
    "updatedAt": "2023-01-01T00:00:00.000Z"
  }
]

Get Document Details

Retrieve details for a specific document.

Endpoint: GET /knowledge/:agentId/files/:fileId

Authentication: Required

Response: Document object with processing status

Delete Document

Delete a document from the knowledge base.

Endpoint: DELETE /knowledge/:agentId/files/:fileId

Authentication: Required

Response: Status 204 No Content

Retry Document Processing

Retry processing for a failed document.

Endpoint: POST /knowledge/:agentId/files/:fileId/retry

Authentication: Required

Response:

{
  "id": 123,
  "status": "processing",
  "message": "Processing started"
}

Chat

Chat with Agent

Send a message to an agent and receive a response.

Endpoint: POST /chat/:agentId

Authentication: Required for private agents, optional for public agents

Request Parameters:

Parameter	Type	Required	Description
`message`	string	Yes	User message
`history`	array	No	Previous conversation history

Response:

{
  "response": "This is the agent's response...",
  "sources": [
    {
      "fileName": "document.pdf",
      "fileId": 123,
      "excerpt": "Relevant content from the document..."
    }
  ]
}

Metrics

Get Agent Metrics

Retrieve usage metrics for an agent.

Endpoint: GET /metrics/agents/:id

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
`period`	string	No	Time period (daily, weekly, monthly)
`from`	ISO date	No	Start date
`to`	ISO date	No	End date

Response:

{
  "totalQueries": 125,
  "averageResponseTime": 2.3,
  "uniqueUsers": 45,
  "topQueries": [
    {
      "query": "How do I reset my password?",
      "count": 15
    }
  ]
}

Integrations

Get Available Integrations

Retrieve available integrations for agents.

Endpoint: GET /marketplace/integrations

Authentication: Required

Response:

[
  {
    "id": 1,
    "name": "Gmail Integration",
    "description": "Connect to Gmail accounts",
    "icon": "data:image/png;base64,...",
    "public": true
  }
]

Update Agent Integrations

Update the integrations for an agent.

Endpoint: PUT /agents/:id/integrations

Authentication: Required

Request Parameters:

Parameter	Type	Required	Description
`integrationIds`	array	Yes	Array of integration IDs

Response: Updated agent object

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

Status Code	Description
200	OK - Request succeeded
201	Created - Resource created successfully
204	No Content - Request succeeded with no response body
400	Bad Request - Invalid parameters
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
413	Payload Too Large - File size exceeds limit (150KB)
500	Internal Server Error - Server issue

Error responses include a JSON object with error details:

{
  "error": "Description of the error"
}

Authentication​

Base URL​

Endpoints​

Agents​

Create Agent​

Get All Agents​

Get Agent​

Get Public Agent​

Update Agent​

Delete Agent​

Knowledge Base​

Upload Document​

Get Knowledge Base​

Get Document Details​

Delete Document​

Retry Document Processing​

Chat​

Chat with Agent​

Metrics​

Get Agent Metrics​

Integrations​

Get Available Integrations​

Update Agent Integrations​

Error Handling​

Authentication

Base URL

Endpoints

Agents

Create Agent

Get All Agents

Get Agent

Get Public Agent

Update Agent

Delete Agent

Knowledge Base

Upload Document

Get Knowledge Base

Get Document Details

Delete Document

Retry Document Processing

Chat

Chat with Agent

Metrics

Get Agent Metrics

Integrations

Get Available Integrations

Update Agent Integrations

Error Handling