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. Assistant replies that use the newer provider-neutral tool-calling format instead carry a tool_mode of PREVIEW or WRITE — see Tool-Calling Messages for how to approve those.

Request Body

Example Request

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

With a file:

{
  "message": "What is this receipt for?",
  "attachment_ids": [8811]
}

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,
  "tool_calls": null,
  "tool_results": null,
  "previews": null,
  "tool_mode": null,
  "approves_message_id": null,
  "attachments": []
}

attachments lists the files sent with the message, in the shape of the Files resource (including thumbnail_url, preview_url and download_url). Chat attachments are read by the assistant but never enter the document pipeline; a user who wants such a file booked uploads it as a document instead.

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"
}

Tool-Calling Messages

This is the current assistant-message format, alongside the legacy codeaction format above. A tool_mode of null means the row predates tool-calling and uses codeaction blocks instead; PREVIEW and WRITE rows carry structured tool_calls, tool_results, and previews instead of embedding them in message (which holds prose only).

1. The assistant replies with a PREVIEW message. tool_calls lists every tool it called; tool_results holds each call’s result; previews describes what any write action would do, with need_approval: true on entries that require a human decision.
2. If no preview entry needs approval, the assistant automatically re-runs the write-capable calls and posts a WRITE message with the same shape, previews[].need_approval now false.
3. If approval is required, the user approves by posting POST /chat/threads/{thread_id}/messages with approves_message_id set to the PREVIEW message’s id (and no message, or an empty one). This re-executes only the calls that needed approval, in write mode, and records a new WRITE message from the assistant.
4. A PREVIEW message can only be approved once — approving it again returns a 400 error.

Example PREVIEW message awaiting approval:

{
  "id": 1050,
  "from_user_id": 2,
  "message": "I can book this as office supplies — want me to go ahead?",
  "tool_mode": "PREVIEW",
  "tool_calls": [
    {
      "id": "call_write",
      "name": "create_journal_entry",
      "arguments": { "data": { "client_account_id": 123 } },
      "needs_approval": true
    }
  ],
  "tool_results": [
    { "tool_call_id": "call_write", "content": "{}", "is_error": false }
  ],
  "previews": [
    { "type": "JournalEntry", "data": {}, "need_approval": true }
  ],
  "approves_message_id": null
}

Approving it:

POST /api/v2/chat/threads/42/messages
{
  "approves_message_id": 1050
}

Resulting WRITE message from the assistant:

{
  "id": 1052,
  "from_user_id": 2,
  "message": "Booked as 6300 (Office Supplies).",
  "tool_mode": "WRITE",
  "tool_calls": [
    {
      "id": "call_write",
      "name": "create_journal_entry",
      "arguments": { "data": { "client_account_id": 123 } },
      "needs_approval": true
    }
  ],
  "tool_results": [
    { "tool_call_id": "call_write", "content": "{\"id\": 55}", "is_error": false }
  ],
  "previews": [
    { "type": "JournalEntry", "data": { "id": 55 }, "need_approval": false }
  ],
  "approves_message_id": null
}

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.