Chat API

Chat threads represent conversations between users, while messages are individual communications within those threads.

Endpoints

Thread Endpoints

List Threads

GET /api/v2/chat/threads

Retrieves a paginated list of chat threads. All filters are optional. When client_account_id is omitted, threads are returned across all of the user’s eligible client accounts.

Query Parameters

Search Examples

Search threads by text content:

GET /api/v2/chat/threads?free_text=invoice

Combine search with other filters:

GET /api/v2/chat/threads?free_text=invoice&client_account_id=123&relation_type=document

Create Thread

POST /api/v2/chat/threads

Creates a new chat thread. The authenticated user is recorded as created_by_id. The user must have access to either the client_account_id or the provider_client_account_id of the thread being created. Messages can be included in the request body to be created together with the thread.

Request Body

Example Request

{
  "client_account_id": 123,
  "provider_client_account_id": 7,
  "subject": "Invoice 1004 - missing VAT code",
  "relation_type": "document",
  "relation_id": 5678,
  "messages": [
    {
      "message": "Could you confirm which VAT code applies to this purchase?"
    }
  ]
}

Response

Returns the created thread with status 201 Created.

{
  "id": 42,
  "created_by_id": 12,
  "created_at": "2026-06-01T09:00:00Z",
  "last_message_created_at": "2026-06-01T09:00:00Z",
  "client_account_id": 123,
  "provider_client_account_id": 7,
  "subject": "Invoice 1004 - missing VAT code",
  "relation_type": "document",
  "relation_id": 5678,
  "is_completed": false,
  "is_archived": false
}

Get Thread

GET /api/v2/chat/threads/{thread_id}

Retrieves a specific chat thread by ID.

Response

Returns the thread object. See Thread Attributes.

Errors

Message Endpoints

Add Message

POST /api/v2/chat/threads/{thread_id}/messages

Adds a new message to a chat thread. The authenticated user is recorded as both from_user_id and created_by_id. The user must have access to either the thread’s client_account_id or provider_client_account_id.

Messages containing a codeaction block trigger automatic processing — the block is first run in preview mode and, if no approval is required, automatically re-run in write mode. See Code Blocks in Messages.

Request Body

Example Request

{
  "message": "Posted as 6300 (Office Supplies). Let me know if that needs adjusting."
}

Response

Returns the created message with status 201 Created. Code blocks in the message field are obscured in the response (see Code Blocks in Messages).

{
  "id": 1042,
  "created_by_id": 12,
  "created_at": "2026-06-01T09:15:00Z",
  "thread_id": 42,
  "from_user_id": 12,
  "message": "Posted as 6300 (Office Supplies). Let me know if that needs adjusting.",
  "is_draft": false,
  "action_items": [],
  "action_mode": null,
  "action_error": false
}

Errors

Update Message

PATCH /api/v2/chat/threads/{thread_id}/messages/{message_id}

Updates an existing message in a chat thread. Useful for editing draft messages before they are finalized, or for replacing message content. The authenticated user is recorded as the new from_user_id.

Only the fields below are accepted in the update payload — thread_id, from_user_id, created_at, and created_by_id cannot be changed.

Request Body

Example Request

Promote a draft to a sent message:

{
  "message": "Confirmed — VAT code 3 (25%) is correct for this purchase.",
  "is_draft": false
}

Response

Returns the updated message with status 201 Created. As with create, code blocks in the message field are obscured.

Errors

Participant Endpoints

List Participants

GET /api/v2/chat/threads/{thread_id}/participants

Returns the participants of a chat thread.

Response

[
  {
    "id": 11,
    "created_by_id": 12,
    "created_at": "2026-06-01T09:00:00Z",
    "user_id": 12,
    "thread_id": 42
  },
  {
    "id": 12,
    "created_by_id": 12,
    "created_at": "2026-06-01T09:01:00Z",
    "user_id": 34,
    "thread_id": 42
  }
]

Errors

Add Participant

POST /api/v2/chat/threads/{thread_id}/participants

Adds a participant (user) to a chat thread. The authenticated user is recorded as created_by_id.

Request Body

Example Request

{
  "user_id": 34
}

Response

Returns the created participant with status 201 Created.

{
  "id": 12,
  "created_by_id": 12,
  "created_at": "2026-06-01T09:01:00Z",
  "user_id": 34,
  "thread_id": 42
}

Errors

Thread Attributes

Message Attributes

Participant Attributes

Code Blocks in Messages

Messages can contain special code blocks that are processed by the system:

Code Block Processing

1. codeaction blocks:
   • First run in preview mode
   • If no errors and no objects need approval, automatically run in write mode
   • A coderesult block is added after the codeaction block
   • Results are posted as a new message
2. approvecodeaction blocks:
   • Finds the last codeaction block in the thread
   • Runs that block in write mode (is_approved=true)
   • Posts the result as a new message containing only the coderesult block

API Response Format

When retrieving messages, code blocks are handled securely:

• Code content in codeaction and coderesult blocks is hidden with “[code hidden]”
• Preview objects from coderesult blocks are extracted into structured data
• The execution mode is included when available

Example response for a message with processed code blocks:

{
    "id": 123,
    "message": "Let's process this:\n```codeaction\n[code hidden]\n```\n```coderesult\n[code hidden]\n```",
    "action_items": [
        {
            "type": "preview",
            "needs_approval": true,
            "id": 1
        }
    ],
    "action_mode": "preview"
}

Example of an approval message:

{
    "id": 124,
    "message": "```approvecodeaction\n```",
    "action_items": [],
    "action_mode": null
}

Example of the result message after approval:

{
    "id": 125,
    "message": "```coderesult\n[code hidden]\n```",
    "action_items": [
        {
            "type": "preview",
            "needs_approval": false,
            "id": 1
        }
    ],
    "action_mode": "write"
}

Relationships

Notes

• All endpoints require authentication.
• All filter parameters on GET /chat/threads are optional. Use free_text only when you need full-text search across thread subjects and messages.
• Access to threads and messages is restricted based on the user’s eligible client accounts. Access is granted if the user can access either the thread’s client_account_id or its provider_client_account_id.
• Error responses:
  • 403 Forbidden: When trying to access a thread the user is not associated with.
  • 404 Not Found: When a specified thread or message doesn’t exist.