Skip to main content
Version: v5.3

Conversations

Overview​

Use the Conversations API call to create, retrieve and delete AI chat conversations. This REST API call allows you to do the following:

A turn is one exchange within a conversation: the prompt a user sent together with the answer the AI team produced for it.

Using the namespace filter​

Note: The nsfilter (namespace filter) query parameter is mandatory for every request. It sets the context, helping you look up resources within that namespace.

Example:

GET /aisvc/api/v1/conversations?nsfilter=your_namespace

Create Conversations​

Endpoint​

POST /aisvc/api/v1/conversations

Request​

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringFilter by namespace.Required
syncBooleanPerform synchronous/asynchronous conversation.Optional
streamBooleanWhen true (together with sync=true), stream the response as Server-Sent Events instead of returning a single JSON body. See Streaming responses.Optional

Headers​

HeaderTypeDescriptionRequired
Accept-LanguageStringLanguage for the text the AI Service generates for this request — the progress captions emitted while the team works, and the message on an error it returns. Supported values are en and ja; any other value, or an omitted header, falls back to en. See Response language.Optional

Body parameters​

ParameterTypeDescriptionRequired
_inputObjectInput payload, with message field.Required
_teamIdStringID of the team.Required
_idStringID of the conversation.Conditional
_externalMcpAuthTokensArray of ObjectOptional auth token overrides for external MCP servers (by _userType).Optional

Note​

New conversation → Omit _id in req.body. Continue conversation → Set _id in req.body using the value returned in the previous response.

External MCP auth tokens (_externalMcpAuthTokens)​

ParameterTypeDescriptionRequired
_externalMcpAuthTokens[]. _userTypeStringExternal MCP server config _userType to apply the token to.Required
_externalMcpAuthTokens[]. _tokenStringAuthorization token value to use for that server (for example, Bearer ...).Required
Body example​
{
"_input": {
"message": "What is BIM?"
},
"_namespaces": ["automation_XjAB8VEB"],
"_teamId": "f73d1653-bf1d-4f00-ad58-543ac48f80a3",
"_externalMcpAuthTokens": [
{
"_userType": "github_mcp",
"_token": "Bearer <token>"
}
]
}

Response codes​

CodeDescription
200Success
400Bad Request

Response​

{
"_id": "8f2dfd89-94f4-4fea-a1a1-d1c6dfdb90c3",
"_turnId": "3d4a17bc-2f8e-4c11-9a03-1c7b5f9a2d41",
"_output": "BIM = Building Information Modeling. At its simplest: BIM is a digital process that creates and uses a coordinated, information‑rich 3D model of a built asset (building, bridge, plant, etc.) to support design, construction and operation across the asset lifecycle.\n\nKey points in plain language\n- A BIM model is not just geometry — it combines 3D objects (walls, doors, beams) with structured data (material, size, cost, fire rating, maintenance schedules).\n- BIM is both a set of technologies (authoring tools, viewers, data exchange formats) and a collaborative working method and workflow (who creates what information, how it’s shared and updated).\n- The goal is better coordination, fewer errors, faster delivery and more useful information for facility operation.\n\nMain uses (often abbreviated as “dimensions”)\n- 3D: visualization and geometric coordination.\n- 4D: schedule/time simulations (construction sequencing).\n- 5D: cost estimating and budgeting.\n- 6D: lifecycle/operation data (asset management, sustainability).\n- Clash detection, quantity takeoffs, energy analysis, prefabrication planning, and handover documentation.\n\nStandards, data exchange and deliverables\n- Common formats: IFC (open standard from buildingSMART), RVT (Revit), DWG, COBie (handover asset data).\n- Common deliverables: federated coordination models, clash reports, quantities, drawing sets, schedules, and an asset information handover pack.\n- International standard: ISO 19650 series (information management using BIM) — widely used for defining responsibilities, common data environment (CDE) and workflows.\n\nRoles and tools\n- Typical roles: BIM Manager, BIM Coordinator, Model Author, CDE Administrator.\n- Popular authoring and collaboration tools: Autodesk Revit, Graphisoft Archicad, Tekla Structures, Bentley Systems, Solibri, Navisworks; cloud platforms include Autodesk Construction Cloud/BIM 360, Trimble Connect, Procore, etc.\n\nBIM maturity / levels\n- “BIM Level” terminology is used differently by region. Common UK concept: Level 0 (CAD), Level 1 (managed CAD), Level 2 (collaborative models with common data environment), Level 3 (fully integrated single models / digital twin).\n- Level of Development (LOD 100–500) describes how much detail and reliability objects in the model have.\n\nBenefits\n- Reduced conflicts and rework (clash detection before construction).\n- Faster, more accurate quantity takeoffs and cost control.\n- Improved coordination between disciplines (architectural/structural/M&E).\n- Better asset information for facility management and lifecycle decisions.\n- Enables prefabrication and offsite construction workflows.\n\nCommon challenges\n- Organizational change, skills gap and training needs.\n- Contractual and liability questions over shared models.\n- Interoperability issues (though IFC is improving this).\n- Upfront time/cost investment in setup, standards and CDE.\n\nIf you want, I can:\n- Give a short comparison of BIM vs CAD.\n- Explain ISO 19650 and what a Common Data Environment is.\n- Show a simple real-world BIM workflow for a small building project.\nWhich would be most useful for you?",
"_usage": {
"_message": { "_input": 4210, "_output": 512, "_total": 4722 },
"_conversation": { "_input": 18030, "_output": 2304, "_total": 20334 }
}
}

_id is the conversation id and _turnId is the id of the turn this request created. _turnId is what addresses the turn-level endpoints — Get Turn by ID, Get Turn Token Usage and Get Turn Trace — so a caller that has just run a turn can read it back without first listing the conversation's turns.

_usage reports the token cost of this request: _message is the turn just completed, and _conversation is the conversation's running total including it. Both count every AI call the turn made — each step of an agent's tool loop, every agent in a multi-agent team, and the embedding calls — not just the final call.

Response language​

Send an Accept-Language header to choose the language of the text the AI Service itself generates for a request:

POST /aisvc/api/v1/conversations?nsfilter=your_namespace&sync=true
Accept-Language: ja

This governs the service-generated text: the process-status captions on a stream, and the message on an error the service returns. It does not translate the agent's answer — that follows the agent's prompt and system message, so an agent instructed in English answers in English whatever this header says. To change the answer's language, write the prompt in that language or configure the agent accordingly.

Supported values are en and ja. An unsupported value or an omitted header falls back to en rather than erroring, so a typo is silent — check the returned text if a request seems not to honour it.

The header applies to all three entry points and takes effect per request, so two conversations in different languages can run concurrently.

Streaming responses​

To receive the response incrementally as the team works, request both sync=true and stream=true and send an Accept: text/event-stream header. The request body is identical to a non-streaming create, and Accept-Language applies here too — it is what the process-status captions and any error frame are rendered in. See Response language.

POST /aisvc/api/v1/conversations?nsfilter=your_namespace&sync=true&stream=true
Accept: text/event-stream

The response is a Server-Sent Events stream. Each frame carries an event: line (the event type) and a data: line with a JSON payload. The stream emits progress events while the team runs, the answer in agent-message chunks, and finishes with a summary then a complete event.

Stream events​

EventPayloadDescription
conversation{ "id": string }Conversation id; emitted once at the start.
team-start{}The team has begun processing the request.
agent-invoked{ "agentName": string }An agent has started its turn.
agent-invocation-message{ "agentName": string, "message": string }The agent's configured invocation message.
llm-analysing{ "agentName": string }The agent's LLM is analysing the request.
process-status{ "phase": string, "description": string, "agentName"?: string }Progress status (for example, knowledge-base search, generating response, agent finished).
tool-invoked{ "toolName": string, "input"?: any, "callId"?: string, "agentName"?: string }A tool was called, with its input arguments.
tool-result{ "toolName": string, "output"?: any, "callId"?: string, "agentName"?: string, "truncated"?: boolean }A tool returned. truncated is true when the output was capped to fit the stream. When the tool call failed, output is a JSON string of the form { "error": string, "status"?: number } (status is the HTTP status, when the failure carried one).
agent-message{ "id"?: string, "agent"?: string, "delta": string, "isFinal": boolean, "path"?: string[] }A chunk of an agent's response text. Concatenate delta values in order to build the full message.
team-done{}All agents have completed their turns.
summary{ "content": string }The final response text; fires once just before token-usage.
token-usage{ "_message": object, "_conversation": object }Token cost of the turn and the conversation's running total, each as { "_input": number, "_output": number, "_total": number }. Fires once, after summary and before complete.
complete{ "_id": string, "_turnId": string, "_output": any }Pipeline finished; carries the conversation id, the id of the turn it created, and the final output (same shape as the non-streaming response).
error{ "message": string }An error occurred during streaming.
close—The stream has closed.

Note: In a multi-agent (supervisory) team, each agent's output is streamed as its own agent-message events; supervisor routing decisions are not streamed.

Example stream​

event: conversation
data: {"id":"8f2dfd89-94f4-4fea-a1a1-d1c6dfdb90c3"}

event: agent-invoked
data: {"agentName":"BIM Analyst"}

event: agent-message
data: {"agent":"BIM Analyst","delta":"BIM = Building ","isFinal":false}

event: agent-message
data: {"agent":"BIM Analyst","delta":"Information Modeling.","isFinal":true}

event: summary
data: {"content":"BIM = Building Information Modeling. ..."}

event: token-usage
data: {"_message":{"_input":4210,"_output":512,"_total":4722},"_conversation":{"_input":18030,"_output":2304,"_total":20334}}

event: complete
data: {"_id":"8f2dfd89-94f4-4fea-a1a1-d1c6dfdb90c3","_turnId":"3d4a17bc-2f8e-4c11-9a03-1c7b5f9a2d41","_output":"BIM = Building Information Modeling. ..."}

Get Conversations​

Endpoint​

GET /aisvc/api/v1/conversations

By default this returns only the conversations owned by the requesting user. Pass allUsers=true to list every user's conversations in the namespace. This requires READ (or *) permission on all conversations, that is on aisvc:conversation:* or aisvc:*:*, in every namespace of the request. READ on individually shared conversations is not enough, and the request is rejected with 403. Pagination and sort order (newest first) are the same in both modes.

Request​

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringFilter by namespace.Required
_offsetNumberOffset for pagination. Defaults to 0.Optional
_pageSizeNumberNumber of results per page. Defaults to 25.Optional
_sortByStringSort by createdAt or updatedAt; records without that timestamp are listed last in either direction. When omitted, results use the default order (creation time, newest first). An unsupported value returns 400.Optional
_sortOrderStringasc or desc. Defaults to desc. Only valid together with _sortBy; an unsupported value returns 400.Optional
allUsersBooleantrue returns every user's conversations in the namespace and requires READ on all conversations. When it is omitted or has any other value, only the requesting user's conversations are returned.Optional

Response codes​

CodeDescription
200Success
400Bad Request
403Forbidden — allUsers=true without READ permission on all conversations

Request examples​

List the requesting user's own conversations:

GET /aisvc/api/v1/conversations?nsfilter=your_namespace&_offset=0&_pageSize=25

List the requesting user's conversations, most recently updated first:

GET /aisvc/api/v1/conversations?nsfilter=your_namespace&_sortBy=updatedAt&_sortOrder=desc

List every user's conversations in the namespace. This requires READ on all conversations:

GET /aisvc/api/v1/conversations?nsfilter=your_namespace&allUsers=true&_offset=0&_pageSize=25

A caller without that permission receives:

{
"source": "ServiceException",
"message": "READ access on all conversations is required to list conversations of all users"
}

Response data example​

{
"_list": [
{
"_id": "88b906cb-aaac-458a-8e6a-b17feeb9cdbe",
"_namespaces": [
"automation_XjAB8VEB"
],
"_title": "What is BIM?",
"_userId": "75957518-60e5-4a52-99cd-a9810fb067ff",
"_status": 1,
"_usage": {
"_input": 18030,
"_output": 2304,
"_total": 20334
},
"_metadata": {
"_createdAt": "1757657412279",
"_updatedById": "75957518-60e5-4a52-99cd-a9810fb067ff",
"_createdById": "75957518-60e5-4a52-99cd-a9810fb067ff",
"_updatedAt": "1757657412279"
}
},
{
"_id": "a9303794-ad67-43fd-abeb-9afa088fb6fb",
"_namespaces": [
"automation_XjAB8VEB"
],
"_title": "Get All assets.",
"_userId": "1fa03865-9c89-4c37-a038-05514771dcf3",
"_status": 1,
"_usage": {
"_input": 940,
"_output": 120,
"_total": 1060
},
"_metadata": {
"_createdAt": "1757053798866",
"_updatedById": "1fa03865-9c89-4c37-a038-05514771dcf3",
"_createdById": "1fa03865-9c89-4c37-a038-05514771dcf3",
"_updatedAt": "1757053806189"
}
}
],
"_offset": 0,
"_pageSize": 15,
"_total": 15
}

Get Conversation by ID​

Endpoint​

GET /aisvc/api/v1/conversations/{id}

Request​

Path parameters​

ParameterTypeDescriptionRequired
idStringID of the conversation.Required

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringFilter by namespace.Required
getChatsBooleanInclude chat messages.Optional
firstNNumberNumber of messages from the start.Optional
lastNNumberNumber of messages from the end.Optional
textToMatchStringFilter messages by vectorized text match.Optional
offsetNumberOffset for message pagination.Optional

Response codes​

CodeDescription
200Success
404Not Found

Response data example​

{
"_id": "b268d1a3-97c6-4e57-ba8e-8272e72900e5",
"_namespaces": [
"auto7470_qFcvagXr"
],
"_title": "List all workspaces.",
"_userId": "f5d6dcd2-582d-4383-b653-5c679ab8db3c",
"_status": 1,
"_usage": {
"_input": 4210,
"_output": 512,
"_total": 4722
},
"_metadata": {
"_createdAt": "1757676118837",
"_updatedById": "f5d6dcd2-582d-4383-b653-5c679ab8db3c",
"_createdById": "f5d6dcd2-582d-4383-b653-5c679ab8db3c",
"_updatedAt": "1757676233031"
},
"_chats": [
{
"_usage": {
"_input": 4210,
"_output": 512,
"_total": 4722
},
"_prompt": "List all workspaces.",
"_llmResponse": "Here are all the workspaces:\n\n1. **Name:** automation1757676105957\n - **ID:** cedf0b81-fc02-40fb-b2aa-63144bd360fe\n - **Short Name:** auto_7470\n - **Description:** automation1757676105957\n\n2. **Name:** automation1757676112455\n - **ID:** 33788826-d660-4280-90f7-c683c9cc3480\n - **Short Name:** auto_1197\n - **Description:** automation1757676112455\n\n3. **Name:** automation1757676112455\n - **ID:** 7fee85c4-2c41-484f-9028-ccdfd0749791\n - **Short Name:** auto_3423\n - **Description:** automation1757676112455\n\n4. **Name:** automation1757676112455\n - **ID:** 4f669674-5ab5-453a-a6bc-683c40dd1be3\n - **Short Name:** auto_5606\n - **Description:** automation1757676112455\n\n5. **Name:** automation1757676112455\n - **ID:** b0cdac99-77bd-40c2-8646-84dbd984c366\n - **Short Name:** auto_7925\n - **Description:** automation1757676112455\n\n6. **Name:** automation1757676112455\n - **ID:** 1e125199-8210-4123-ab29-cea6384e1b12\n - **Short Name:** auto_8213\n - **Description:** automation1757676112455\n\nIf you need more details about any specific workspace, feel free to ask!"
}
]
}

_usage on the conversation is the running total across all of its turns; _usage inside _chats is the cost of that individual turn. A conversation created before token tracking existed reports zeros rather than omitting the field.

Note: getChats does not return the id of each turn. To address an individual turn — for its token breakdown or its trace — use Get conversation turns, which returns _id for each. A turn you have just created is simpler still: the conversation request returns its id as _turnId. getChats remains supported and is expected to be deprecated in favour of the turn reads.

Get Conversation Turns​

Returns the turns of a conversation, oldest first. Unlike getChats on Get conversation by ID, each turn includes its _id, which the turn-level calls below require.

Use this to work through a conversation's history. To read back a turn you have just created, take _turnId from the conversation response instead — see Create conversations — which saves listing the turns to find your own.

Endpoint​

GET /aisvc/api/v1/conversations/{id}/turns

Request​

Path parameters​

ParameterTypeDescriptionRequired
idStringID of the conversation.Required

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringFilter by namespace.Required
_offsetNumberOffset for pagination. Defaults to 0.Optional
_pageSizeNumberPage size. Defaults to 25.Optional

Response codes​

CodeDescription
200Success
400Bad Request
403Forbidden
404Not Found

Response data example​

{
"_list": [
{
"_id": "3d4a17bc-2f8e-4c11-9a03-1c7b5f9a2d41",
"_conversationId": "b268d1a3-97c6-4e57-ba8e-8272e72900e5",
"_teamId": "6f1b2c33-9d40-4e21-8a77-0c2e5b7d1a88",
"_prompt": "List all workspaces.",
"_llmResponse": "Here are all the workspaces: ...",
"_duration": 8231,
"_status": 1,
"_usage": {
"_input": 4210,
"_output": 512,
"_total": 4722
},
"_metadata": {
"_createdAt": "1757676118837",
"_createdById": "f5d6dcd2-582d-4383-b653-5c679ab8db3c",
"_updatedAt": "1757676127068",
"_updatedById": "f5d6dcd2-582d-4383-b653-5c679ab8db3c"
}
}
],
"_offset": 0,
"_pageSize": 1,
"_total": 12
}

Get Turn by ID​

Endpoint​

GET /aisvc/api/v1/conversations/{id}/turns/{turnId}

Request​

Path parameters​

ParameterTypeDescriptionRequired
idStringID of the conversation.Required
turnIdStringID of the turn.Required

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringFilter by namespace.Required

Response codes​

CodeDescription
200Success
400Bad Request
403Forbidden
404Not Found

Response data example​

{
"_id": "3d4a17bc-2f8e-4c11-9a03-1c7b5f9a2d41",
"_conversationId": "b268d1a3-97c6-4e57-ba8e-8272e72900e5",
"_teamId": "6f1b2c33-9d40-4e21-8a77-0c2e5b7d1a88",
"_prompt": "List all workspaces.",
"_llmResponse": "Here are all the workspaces: ...",
"_duration": 8231,
"_status": 1,
"_usage": {
"_input": 4210,
"_output": 512,
"_total": 4722
},
"_metadata": {
"_createdAt": "1757676118837",
"_createdById": "f5d6dcd2-582d-4383-b653-5c679ab8db3c",
"_updatedAt": "1757676127068",
"_updatedById": "f5d6dcd2-582d-4383-b653-5c679ab8db3c"
}
}

Note: A turn is looked up within the conversation in the path. A turnId belonging to a different conversation returns 404.

Get Conversation Token Usage​

Returns the conversation's token total together with the breakdown of what incurred it — which agent, on which model, over how many AI calls — summed across every turn in the conversation.

Endpoint​

GET /aisvc/api/v1/conversations/{id}/tokenusage

Request​

Path parameters​

ParameterTypeDescriptionRequired
idStringID of the conversation.Required

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringFilter by namespace.Required

Response codes​

CodeDescription
200Success
400Bad Request
403Forbidden
404Not Found

Response data example​

{
"_conversationId": "b268d1a3-97c6-4e57-ba8e-8272e72900e5",
"_usage": {
"_input": 18432,
"_output": 2310,
"_total": 20742
},
"_sources": [
{
"_kind": "agent",
"_name": "data-model-specialist",
"_displayName": "Data Model Specialist",
"_model": "gpt-4o",
"_resolvedModel": "gpt-4o-2024-11-20",
"_provider": "openai",
"_usage": { "_input": 15980, "_output": 1902, "_total": 17882 },
"_calls": 14
},
{
"_kind": "summarization",
"_name": "summary",
"_model": "gpt-4o",
"_resolvedModel": "gpt-4o-2024-11-20",
"_provider": "openai",
"_usage": { "_input": 402, "_output": 6, "_total": 408 },
"_calls": 2
},
{
"_kind": "embedding",
"_name": "prompt",
"_model": "text-embedding-3-large",
"_resolvedModel": "text-embedding-3-large",
"_provider": "openai",
"_usage": { "_input": 52, "_output": 0, "_total": 52 },
"_calls": 2
}
]
}

Response fields​

FieldDescription
_usageThe stored total. The entries in _sources sum to it.
_sourcesOne entry per source and served model, heaviest first.
_kindWhat incurred the usage: agent, embedding or summarization.
_nameThe agent's user type, or the role of the call in the turn (prompt, response, summary).
_displayNameThe agent's display name as configured when it ran. Absent for non-agent sources.
_modelThe model as configured on the agent, for example gpt-4o.
_resolvedModelThe model the provider actually served, for example gpt-4o-2024-11-20. These differ when a model alias points at a dated snapshot, and billing follows the resolved model.
_provideropenai or anthropic.
_callsHow many AI calls this source made. An agent that looped over a tool a dozen times appears once, with _calls of 12.

Note: A conversation that predates token tracking returns zeros and an empty _sources list, with a 200 — not a 404.

Get Turn Token Usage​

The same breakdown, narrowed to a single turn. This is where a single expensive turn — for example an agent looping over a tool — becomes visible.

Endpoint​

GET /aisvc/api/v1/conversations/{id}/turns/{turnId}/tokenusage

Request​

Path parameters​

ParameterTypeDescriptionRequired
idStringID of the conversation.Required
turnIdStringID of the turn.Required

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringFilter by namespace.Required

Response codes​

CodeDescription
200Success
400Bad Request
403Forbidden
404Not Found

Response data example​

{
"_conversationId": "b268d1a3-97c6-4e57-ba8e-8272e72900e5",
"_turnId": "3d4a17bc-2f8e-4c11-9a03-1c7b5f9a2d41",
"_usage": {
"_input": 4210,
"_output": 512,
"_total": 4722
},
"_sources": [
{
"_kind": "agent",
"_name": "data-model-specialist",
"_displayName": "Data Model Specialist",
"_model": "gpt-4o",
"_resolvedModel": "gpt-4o-2024-11-20",
"_provider": "openai",
"_usage": { "_input": 4158, "_output": 512, "_total": 4670 },
"_calls": 3
},
{
"_kind": "embedding",
"_name": "prompt",
"_model": "text-embedding-3-large",
"_resolvedModel": "text-embedding-3-large",
"_provider": "openai",
"_usage": { "_input": 52, "_output": 0, "_total": 52 },
"_calls": 1
}
]
}

Fields are the same as Get conversation token usage, with _turnId identifying the turn and _usage reporting that turn's total rather than the conversation's.

Note: A turn's summarization cost is added shortly after the answer is returned, so a turn read immediately after a conversation call can report a slightly lower total than the same turn read a moment later.

Get Conversation Trace​

The archived execution record for a conversation: what the Team actually did to produce each answer — which prior turns and knowledge-base passages were put in front of the model, which agents ran and in what order, every tool call with its arguments and its result, and where a turn failed.

This is the record support and audit read after the fact. Unlike the stream events, which exist only while a conversation runs and only for callers that asked to stream, the trace is captured for every conversation regardless of how it was invoked, and is stored until it is purged by the configured retention period.

Note: Traces exist only for conversations run after this feature was deployed. An older conversation returns 200 with an empty _list, not 404.

Endpoint​

GET /aisvc/api/v1/conversations/{id}/trace

Request​

Path parameters​

ParameterTypeDescriptionRequired
idStringID of the conversation.Required

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringFilter by namespace.Required
_offsetIntegerPaging offset, 0 or greater. Defaults to 0.Optional
_pageSizeIntegerPage size, between 1 and 200. Defaults to 25.Optional
_eventTypeStringFilter to one or more event types. Repeat the parameter to pass several. Omit it to return every type.Optional
_turnIdStringNarrow to a single turn. Equivalent to calling Get Turn Trace.Optional

Filtering by several event types — repeat _eventType once per value; values combine as OR:

GET /aisvc/api/v1/conversations/{id}/trace?nsfilter=your_namespace&_eventType=tool_invoked&_eventType=tool_result

A comma-separated list is not supported. ?_eventType=tool_invoked,tool_result is read as a single unknown event type and returns 400 naming it, rather than returning an empty page.

Paging is capped at 200 because payloads are stored whole — a single tool result can be large. A _pageSize above the cap returns 400 stating the limit rather than silently returning fewer rows, so a caller can always distinguish a capped page from the end of the data.

Response codes​

CodeDescription
200Success
400Bad Request — malformed id, unknown _eventType, or invalid paging value
403Forbidden — the caller cannot read the conversation
404Not Found — the conversation does not exist

Response data example​

{
"_list": [
{
"_id": "0f0d0a5e-8b21-4c76-9f3a-6a1d2e4b7c90",
"_conversationId": "b268d1a3-97c6-4e57-ba8e-8272e72900e5",
"_turnId": "3d4a17bc-2f8e-4c11-9a03-1c7b5f9a2d41",
"_sequence": 4,
"_eventType": "tool_invoked",
"_agentName": "Data Model Specialist",
"_toolName": "GetNamedUserItemTool",
"_callId": "call_8fJ2xQ",
"_payload": {
"input": { "_name": "Doors", "_namespaces": ["your_namespace"] }
},
"_metadata": { "_createdAt": 1755000000000, "_createdById": "auth0|..." }
},
{
"_id": "1a7c33d2-5e90-4a18-8c2f-7b3e1d6f4a52",
"_conversationId": "b268d1a3-97c6-4e57-ba8e-8272e72900e5",
"_turnId": "3d4a17bc-2f8e-4c11-9a03-1c7b5f9a2d41",
"_sequence": 5,
"_eventType": "tool_result",
"_agentName": "Data Model Specialist",
"_toolName": "GetNamedUserItemTool",
"_callId": "call_8fJ2xQ",
"_payload": { "output": "{\"_list\":[{\"_id\":\"...\"}]}" },
"_metadata": { "_createdAt": 1755000000000, "_createdById": "auth0|..." }
}
],
"_offset": 0,
"_pageSize": 2,
"_total": 27
}

Response fields​

FieldTypeDescription
_idStringEvent id.
_conversationIdStringConversation the event belongs to.
_turnIdStringTurn the event belongs to.
_sequenceIntegerExecution order within the turn, starting at 1.
_eventTypeStringOne of the event types below.
_agentNameStringDisplay name of the agent the event relates to, where applicable.
_toolNameStringTool name, for tool events.
_callIdStringProvider tool-call id, pairing a tool_invoked with its tool_result.
_payloadObjectEvent body, returned exactly as archived. See the catalogue below.
_metadataObjectStandard audit metadata.

Results are returned in execution order. _payload is never truncated: a tool result that was capped at 8 KB on the stream is returned here in full.

Event types​

_eventTypeEmitted when_payload
history_contextThe prior-turn context was assembled and fitted to the budget{ strategy, turns[], selectedCount, truncated } — each turn with its id, how it was selected, and the text the model received
knowledge_contextAn agent's knowledge-base text was assembled and fitted{ agentName, knowledgeBases[], characters, truncated, text? }
attachment_statusA file attachment was selected, loaded, unavailable or failed{ agentName, provider, ref, name, version, fileId, fileVersionId, scope, status }
agent_invokedAn agent began its turn{ agentName, invocationMessage? }
agent_messageAn agent finished and returned its output{ agentName, content }
supervisor_routeA supervisor chose the next agent (supervisory teams){ supervisor, selected, reason? }
tool_invokedA tool call was issued{ toolName, callId, agentName, input }
tool_resultA tool call returned{ toolName, callId, agentName, output, artifact? }
process_statusAn agent finished its span{ phase: "agent_finished", agentName }
errorThe turn failed{ message, status?, failedAgent? }

Note: The trace is deliberately narrower than the stream. token-usage, llm-analysing, process-status phases other than agent_finished, agent-invocation-message and the agent-message text chunks are delivered to streaming clients but not archived — token usage because Get Turn Token Usage is the authoritative record, and the rest because they are progress detail rather than a record of what the model did. An agent's finished output is archived, once per invocation, as agent_message.

Note: artifact on tool_result carries the second half of an MCP tool's content_and_artifact response — embedded resources, structured content and metadata. It is archived but is not sent on the stream.

Get Turn Trace​

The same record, narrowed to a single turn. This is the usual starting point when a customer reports one bad answer: the turn id comes back on the conversation response as _turnId, so no lookup is needed.

Endpoint​

GET /aisvc/api/v1/conversations/{id}/turns/{turnId}/trace

Request​

Path parameters​

ParameterTypeDescriptionRequired
idStringID of the conversation.Required
turnIdStringID of the turn.Required

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringFilter by namespace.Required
_offsetIntegerPaging offset, 0 or greater. Defaults to 0.Optional
_pageSizeIntegerPage size, between 1 and 200. Defaults to 25.Optional
_eventTypeStringFilter to one or more event types. Repeat the parameter to pass several.Optional

Response codes​

CodeDescription
200Success
400Bad Request — malformed id, unknown _eventType, or invalid paging value
403Forbidden — the caller cannot read the conversation
404Not Found — the conversation does not exist

Response data example​

{
"_list": [
{
"_id": "7c1b02aa-3d55-4f8e-9b60-2e7a4c1f5d38",
"_conversationId": "b268d1a3-97c6-4e57-ba8e-8272e72900e5",
"_turnId": "3d4a17bc-2f8e-4c11-9a03-1c7b5f9a2d41",
"_sequence": 1,
"_eventType": "agent_invoked",
"_agentName": "Data Model Specialist",
"_payload": { "agentName": "Data Model Specialist" },
"_metadata": { "_createdAt": 1755000000000, "_createdById": "auth0|..." }
},
{
"_id": "9e44f7b1-6a02-4c93-8d17-5f2b8e3a7c64",
"_conversationId": "b268d1a3-97c6-4e57-ba8e-8272e72900e5",
"_turnId": "3d4a17bc-2f8e-4c11-9a03-1c7b5f9a2d41",
"_sequence": 2,
"_eventType": "agent_message",
"_agentName": "Data Model Specialist",
"_payload": {
"agentName": "Data Model Specialist",
"content": "There are 42 doors in the model, of which 12 are fire-rated."
},
"_metadata": { "_createdAt": 1755000000000, "_createdById": "auth0|..." }
}
],
"_offset": 0,
"_pageSize": 2,
"_total": 9
}

Fields and event types are the same as Get conversation trace, with _sequence running from 1 for the turn.

Note: A turn's events are archived together once the answer has been persisted, so they share one _metadata._createdAt. Use _sequence, not the timestamp, to read a turn in execution order.

Delete Conversation​

Permanently deletes one conversation along with everything recorded under it: its turns, attachment references, token usage and traces. The delete is irreversible. Deleted data cannot be recovered, and the conversation cannot be resumed. Files in the File Service that were attached to the conversation are not deleted. Only the conversation's references to them are removed.

A user with the Platform Manager role can delete any user's conversation in the namespace given in nsfilter, without holding conversation permissions there. Every other user needs DELETE (or *) permission on the conversation, such as on aisvc:conversation:{id}, aisvc:conversation:* or aisvc:*:*.

Endpoint​

DELETE /aisvc/api/v1/conversations/{id}

Request​

Path parameters​

ParameterTypeDescriptionRequired
idStringThe ID of the conversation.Required

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace the conversation belongs to.Required

Response codes​

CodeDescription
204Deleted. There is no response body.
400Bad Request. The id is not a valid UUID, or nsfilter is missing.
403Forbidden. The caller is not a Platform Manager and has no DELETE permission on the conversation.
404Not Found. No conversation with this ID exists in the namespace.

Request example​

DELETE /aisvc/api/v1/conversations/8f2dfd89-94f4-4fea-a1a1-d1c6dfdb90c3?nsfilter=your_namespace

Delete All Conversations in a Namespace​

Permanently deletes every user's conversations in one namespace, along with all their turns, attachment references, token usage and traces. The delete is irreversible. Because there is no undo, the request has to say so explicitly with _scope=all, and nsfilter has to name exactly one namespace.

This is allowed for a user with the Platform Manager role in any namespace. It is also allowed for a user who holds DELETE (or *) on all conversations in the namespace, which means aisvc:conversation:* or aisvc:*:*. DELETE on individual conversations is not enough, and the request is rejected with 403.

The delete runs as a single transaction. It removes all of the namespace's conversations, or none of them if anything fails.

Endpoint​

DELETE /aisvc/api/v1/conversations

Request​

Query parameters​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace to delete all conversations from. Give exactly one namespace.Required
_scopeStringMust be all. Confirms that every conversation in the namespace is deleted.Required

Response codes​

CodeDescription
200Deleted. The response body gives the number of conversations deleted.
400Bad Request. _scope=all is missing, or nsfilter does not name exactly one namespace.
403Forbidden. The caller is not a Platform Manager and has no DELETE permission on all conversations in the namespace.

Request example​

DELETE /aisvc/api/v1/conversations?nsfilter=your_namespace&_scope=all

Response data example​

{
"_deleted": 42
}

A namespace with no conversations returns { "_deleted": 0 }.

Error response examples​

Without _scope=all:

{
"message": "Deleting all conversations in a namespace is irreversible and requires _scope=all"
}

With more than one namespace in nsfilter:

{
"message": "Deleting all conversations requires exactly one namespace in nsfilter"
}

A caller who is not a Platform Manager and holds DELETE only on individual conversations in the namespace:

{
"source": "ServiceException",
"message": "Platform Manager role or DELETE access on all conversations is required to delete all conversations in a namespace"
}

A caller who is not a Platform Manager and holds no DELETE permission on conversations in the namespace at all is rejected before the request reaches the service:

{
"message": "Authorization check failed - DELETE Access Not Allowed for aisvc:conversation:*"
}

Auditing deletes​

Every committed delete, whether of a single conversation or of a whole namespace, is recorded in two ways:

  • One ResourceHardDeleted event is written per deleted conversation, in the same transaction as the delete. It has resource type com.invicara.aisvc.event.resource.Conversation. The event records the ID of the user who deleted it, the time, the request ID, and the conversation's ID, namespaces, title and owner.
  • An info-level Conversation history deleted log entry is written with audit: "conversation.delete". It records the scope (single or namespace), the deleting user's ID, whether they acted as a Platform Manager, the namespace, and the IDs of the deleted conversations.