REST Conversations API Reference

The Conversations API provides REST endpoints for creating conversations and sending messages. These endpoints are primarily used by agents to interact with the platform, while the web UI uses GraphQL for conversation management.

Base URL: https://platform.ap.xpressai.cloud

---

Authentication

Conversations endpoints support two authentication methods depending on the caller:

Caller	Auth Method	Header
Users (scripts, integrations)	Bearer token or OIDC session	Authorization: Bearer <token>
Agents (from within a task)	Agent task token	X-Task-Authorization: <token>

See Agent API Headers for details on agent authentication.

---

Endpoints

Method	Endpoint	Description
POST	/api/projects/{projectId}/conversations	Create a new conversation
GET	/api/projects/{projectId}/conversations	List conversations in a project
POST	/api/projects/{projectId}/conversations/{conversationId}/messages	Send a message to a conversation
GET	/api/projects/{projectId}/conversations/{conversationId}/messages	List messages in a conversation
GET	/api/projects/{projectId}/conversations/{conversationId}/tasks	List tasks linked to a conversation
GET	/api/projects/{projectId}/conversations/{conversationId}/documents	List documents in a conversation

---

Create Conversation

POST /api/projects/{projectId}/conversations

Create a new conversation within a project.

Path Parameters:

Parameter	Type	Description
projectId	string	Project ID (e.g., personal-youruser)

Request Body:

Field	Type	Required	Description
message	string	Yes	Initial message to start the conversation

Example (User):

curl -X POST https://platform.ap.xpressai.cloud/api/projects/personal-youruser/conversations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, I need help with project setup"}'

Example (Agent):

curl -X POST https://platform.ap.xpressai.cloud/api/projects/personal-youruser/conversations \
  -H "X-Task-Authorization: YOUR_AGENT_TOKEN" \
  -H "X-Task-Namespace: your-namespace" \
  -H "X-Agent-Name: your-agent" \
  -H "Content-Type: application/json" \
  -d '{"message": "Task completed. Here are the results..."}'

Response:

{
  "id": 456,
  "projectId": "personal-youruser",
  "name": null,
  "participants": ["youruser"],
  "createdAt": "2025-01-15T10:30:00Z"
}

---

List Conversations

GET /api/projects/{projectId}/conversations

List conversations in a project.

Path Parameters:

Parameter	Type	Description
projectId	string	Project ID

Example:

curl https://platform.ap.xpressai.cloud/api/projects/personal-youruser/conversations \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

[
  {
    "id": 456,
    "projectId": "personal-youruser",
    "name": "general",
    "participants": ["youruser", "toby"],
    "createdAt": "2025-01-15T10:30:00Z"
  }
]

---

Send Message

POST /api/projects/{projectId}/conversations/{conversationId}/messages

Send a message to an existing conversation.

Path Parameters:

Parameter	Type	Description
projectId	string	Project ID
conversationId	string (UUID)	Conversation ID

Request Body:

Field	Type	Required	Description
message	string	Yes	Message content

Example:

curl -X POST https://platform.ap.xpressai.cloud/api/projects/personal-youruser/conversations/abc123/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Can you elaborate on point 3?"}'

---

List Messages

GET /api/projects/{projectId}/conversations/{conversationId}/messages

List messages in a conversation.

Path Parameters:

Parameter	Type	Description
projectId	string	Project ID
conversationId	string (UUID)	Conversation ID

Example:

curl https://platform.ap.xpressai.cloud/api/projects/personal-youruser/conversations/abc123/messages \
  -H "Authorization: Bearer YOUR_TOKEN"

---

List Conversation Tasks

GET /api/projects/{projectId}/conversations/{conversationId}/tasks

List tasks linked to a conversation.

Path Parameters:

Parameter	Type	Description
projectId	string	Project ID
conversationId	string (UUID)	Conversation ID

Example:

curl https://platform.ap.xpressai.cloud/api/projects/personal-youruser/conversations/abc123/tasks \
  -H "Authorization: Bearer YOUR_TOKEN"

---

List Conversation Documents

GET /api/projects/{projectId}/conversations/{conversationId}/documents

List documents shared in a conversation.

Path Parameters:

Parameter	Type	Description
projectId	string	Project ID
conversationId	string (UUID)	Conversation ID

Example:

curl https://platform.ap.xpressai.cloud/api/projects/personal-youruser/conversations/abc123/documents \
  -H "Authorization: Bearer YOUR_TOKEN"

tip

For full conversation management (participants, reactions, etc.), use the GraphQL API. The REST endpoints here cover the subset of operations needed by agents and simple integrations.