Agent API (Sample)

The following specifications describe a standard API used by the Code Capsules chat window to communicate with the agent.

Send a message to the AI agent

post

Send a message to the conversational AI agent and receive a complete response. For streaming responses, use the /message/stream endpoint instead.

Authorizations

ApiKeyAuthEmailAuth

X-CC-API-KEYstringRequired

API key for authentication

Body

application/json

datestring · date-timeRequired

Timestamp of the message

Example: 2025-11-07T10:30:00Z

Responses

200

Successful response from the AI agent

application/json

400

Bad request - Message content is required

application/json

401

Unauthorized - Invalid or missing authentication headers

application/json

500

Internal server error

application/json

post

/api/chat/message

HTTPcURLJavaScriptPython

POST /api/chat/message HTTP/1.1
Host: 
X-CC-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 80

{
  "content": [
    {
      "type": "text",
      "text": "Hello there"
    }
  ],
  "date": "2025-11-07T10:30:00Z"
}

{
  "data": [
    {
      "role": "user",
      "content": [
        {
          "text": "Hello there"
        }
      ],
      "date": "2025-12-16T03:13:22.767Z"
    }
  ],
  "success": true
}

Stream a message from the AI agent

post

Send a message to the conversational AI agent and receive a streaming response. The response is sent as Server-Sent Events (SSE) with each chunk containing the type and content.

Authorizations

ApiKeyAuthEmailAuth

X-CC-API-KEYstringRequired

API key for authentication

Body

application/json

datestring · date-timeRequired

Timestamp of the message

Example: 2025-11-07T10:30:00Z

Responses

200

Successful streaming response from the AI agent

text/event-stream

Responsestring

Server-Sent Events stream containing message chunks

400

Bad request - Message is required

application/json

401

Unauthorized - Invalid or missing authentication headers

application/json

500

Internal server error

application/json

post

/api/chat/message/stream

HTTPcURLJavaScriptPython

POST /api/chat/message/stream HTTP/1.1
Host: 
X-CC-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 80

{
  "content": [
    {
      "type": "text",
      "text": "Hello there"
    }
  ],
  "date": "2025-11-07T10:30:00Z"
}

text

Get chat history for the authenticated user

get

Retrieve the complete chat history for the currently authenticated user, including all previous conversations.

Authorizations

ApiKeyAuthEmailAuth

X-CC-API-KEYstringRequired

API key for authentication

Responses

200

Chat history retrieved successfully

application/json

401

Unauthorized - User not authenticated or missing user information

application/json

500

Internal server error

application/json

get

/api/chat/history

HTTPcURLJavaScriptPython

GET /api/chat/history HTTP/1.1
Host: 
X-CC-API-KEY: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "role": "user",
      "content": [
        {
          "text": "Hello there"
        }
      ],
      "date": "2025-12-16T03:13:22.767Z"
    }
  ],
  "success": true
}

Add text context to the vector store

post

Add text content to the vector store for use in RAG (Retrieval-Augmented Generation) context retrieval.

Authorizations

ApiKeyAuthEmailAuth

X-CC-API-KEYstringRequired

API key for authentication

Body

application/json

textstringRequired

The text content to be added to the vector store

Responses

200

Context added successfully

application/json

400

Bad request - Context text is required

application/json

401

Unauthorized - Invalid or missing authentication headers

application/json

500

Internal server error

application/json

post

/api/context/text

HTTPcURLJavaScriptPython

POST /api/context/text HTTP/1.1
Host: 
X-CC-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "text": "text"
}

{
  "success": true
}

Add context from URL to the vector store

post

Fetch content from a URL and add it to the vector store for use in RAG (Retrieval-Augmented Generation) context retrieval.

Authorizations

ApiKeyAuthEmailAuth

X-CC-API-KEYstringRequired

API key for authentication

Body

application/json

urlstring · uriRequired

The URL to fetch content from

Example: https://example.com/article

Responses

200

Context added successfully

application/json

400

Bad request - URL is required

application/json

401

Unauthorized - Invalid or missing authentication headers

application/json

500

Internal server error

application/json

post

/api/context/url

HTTPcURLJavaScriptPython

POST /api/context/url HTTP/1.1
Host: 
X-CC-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "url": "https://example.com/article"
}

{
  "success": true
}

Schemas