Unisson chat API
The chat API from Unisson — 18 operation(s) for chat.
The chat API from Unisson — 18 operation(s) for chat.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/unisson-chat-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Unisson agent-evals Chat API
version: 1.0.0
servers:
- url: https://api.unisson.ai
description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: chat
paths:
/api/v1/chat/conversations:
post:
tags:
- chat
summary: Create Conversation
description: 'Create a new chat conversation. Agents join by being tagged —
@-mentions in messages or the optional ``tagged_agent_id`` here.'
operationId: create_conversation_api_v1_chat_conversations_post
security:
- HTTPBearer: []
parameters:
- name: tagged_agent_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
description: Optionally tag an agent onto the new conversation (the agent detail page's 'New chat' button) — same additive mechanism as an @-mention, recorded in chat_conversation_agents.
title: Tagged Agent Id
description: Optionally tag an agent onto the new conversation (the agent detail page's 'New chat' button) — same additive mechanism as an @-mention, recorded in chat_conversation_agents.
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChatConversationResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- chat
summary: List Conversations
description: "List chat conversations, most recent first.\n\nScoping rules:\n * ``agent_id`` set — tagging an agent makes the conversation visible\n on that agent's page to the whole org, so we return every\n conversation that tagged the agent regardless of who created it.\n * ``agent_id`` unset — personal scope; only the caller's own\n conversations are listed (URL-share is the only way teammates reach\n someone else's personal thread).\n\n``scope`` then narrows the list (sidebar filter tabs):\n * ``my_customers`` — conversations linked to a customer the caller\n belongs to.\n * ``personal`` — conversations the caller started or authored a user\n message in."
operationId: list_conversations_api_v1_chat_conversations_get
security:
- HTTPBearer: []
parameters:
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
default: 1
title: Page
- name: page_size
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
default: 50
title: Page Size
- name: agent_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
description: Filter to conversations that tagged this agent. Omit to list the user's own conversations.
title: Agent Id
description: Filter to conversations that tagged this agent. Omit to list the user's own conversations.
- name: search
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Search
- name: scope
in: query
required: false
schema:
enum:
- all
- my_customers
- personal
type: string
description: 'Sidebar filter: ''my_customers'' keeps conversations linked to a customer the caller belongs to; ''personal'' keeps conversations the caller started or wrote a message in.'
default: all
title: Scope
description: 'Sidebar filter: ''my_customers'' keeps conversations linked to a customer the caller belongs to; ''personal'' keeps conversations the caller started or wrote a message in.'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChatConversationListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/chat/conversations/builder:
post:
tags:
- chat
summary: Get Or Create Builder Conversation
description: 'Get-or-create the single Agent-Builder conversation for an agent.
Members-only surface. Exactly one persistent thread per agent
(``builder_agent_id``), or one lazy draft per user (``is_new_agent_draft``)
for the "New agent" flow — the partial unique indexes make get-or-create
race-safe. Excluded from every conversation list.'
operationId: get_or_create_builder_conversation_api_v1_chat_conversations_builder_post
security:
- HTTPBearer: []
parameters:
- name: agent_id
in: query
required: true
schema:
type: string
description: The agent whose builder chat to open, or the literal 'new' to open the caller's lazy new-agent draft thread.
title: Agent Id
description: The agent whose builder chat to open, or the literal 'new' to open the caller's lazy new-agent draft thread.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChatConversationResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/chat/conversations/{conversation_id}:
get:
tags:
- chat
summary: Get Conversation
description: "Get a conversation with a bounded window of messages.\n\nPagination is cursor-based walking backwards in conversation order:\n - No cursor: return the newest ``limit`` messages.\n - ``before_message_id``: return the ``limit`` messages immediately\n older than the cursor.\nThe response's ``next_cursor`` + ``has_more`` let the client fetch the\nnext older page. Messages are returned in chronological order."
operationId: get_conversation_api_v1_chat_conversations__conversation_id__get
security:
- HTTPBearer: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
format: uuid
title: Conversation Id
- name: before_message_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Before Message Id
- name: limit
in: query
required: false
schema:
type: integer
default: 100
title: Limit
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChatConversationDetailResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- chat
summary: Delete Conversation
description: Soft-delete a conversation.
operationId: delete_conversation_api_v1_chat_conversations__conversation_id__delete
security:
- HTTPBearer: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
format: uuid
title: Conversation Id
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/chat/conversations/{conversation_id}/context:
get:
tags:
- chat
summary: Get Conversation Context
description: 'What is actually *in* this conversation''s chat context: the connectors
the chat agent invoked, plus the customers and agents whose context the
next turn will load — derived through the same capped helpers the chat
turn uses, so the panel never shows an agent/customer that contributes no
prompt block.
Powers the right-sidebar "Context" panel. Unlike ``get_conversation`` this
scans **all** of the conversation''s tool-call rows (not a paginated message
window), so the integration list is complete however far back the user has
scrolled.'
operationId: get_conversation_context_api_v1_chat_conversations__conversation_id__context_get
security:
- HTTPBearer: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
format: uuid
title: Conversation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationContextResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/chat/files:
get:
tags:
- chat
summary: List Chat Files
description: "List VFS files visible in a chat, with presigned download URLs.\n\nExactly one of ``agent_id`` or ``conversation_id`` must be supplied:\n\n* ``agent_id`` — list the agent's persistent workspace (under its own\n ``/agents/<slug>/``).\n* ``conversation_id`` — list one ``/agents/<slug>/`` per tagged agent plus\n ``/chat/`` for the conversation itself.\n\nReturned ``path`` values are mount-prefixed (``/agents/<slug>/...`` or\n``/chat/...``) so identical filenames across scopes don't collide in the\nlisting or in subsequent delete calls."
operationId: list_chat_files_api_v1_chat_files_get
security:
- HTTPBearer: []
parameters:
- name: conversation_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Conversation Id
- name: agent_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Agent Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationFileListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- chat
summary: Delete Chat File
description: 'Delete a file from the chat-visible workspace.
The path''s leading mount (``/agents/<slug>/`` or ``/chat/``) selects the
workspace; the remaining segment is the workspace-relative key.
Refuses paths nested under any hidden workspace subtree (see
``HIDDEN_WORKSPACE_PREFIXES``) so the listing filter and the delete
surface stay consistent.'
operationId: delete_chat_file_api_v1_chat_files_delete
security:
- HTTPBearer: []
parameters:
- name: path
in: query
required: true
schema:
type: string
description: Mount-prefixed path returned by GET /chat/files.
title: Path
description: Mount-prefixed path returned by GET /chat/files.
- name: conversation_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Conversation Id
- name: agent_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Agent Id
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/chat/files/content:
get:
tags:
- chat
summary: Get Chat File Content
description: 'Stream a workspace file''s bytes through the backend.
Powers the in-app file viewer. Going through the backend (instead of
fetching the presigned download URL directly from the SPA) sidesteps S3
CORS — the bucket needn''t allow every dev/preview origin.'
operationId: get_chat_file_content_api_v1_chat_files_content_get
security:
- HTTPBearer: []
parameters:
- name: path
in: query
required: true
schema:
type: string
description: Mount-prefixed path returned by GET /chat/files.
title: Path
description: Mount-prefixed path returned by GET /chat/files.
- name: conversation_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Conversation Id
- name: agent_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Agent Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/chat/conversations/{conversation_id}/stop:
post:
tags:
- chat
summary: Stop Conversation Stream
description: 'User-initiated stop of the in-flight chat LLM stream.
Halts the chat producer without cancelling spawned CUA runs — those
continue to completion and the chat-run supervisor still drives an
auto-turn when the run terminates. Idempotent: returns 204 even when
no producer is running so the FE can fire-and-forget on Stop clicks.
The Postgres request is authoritative across workers; the legacy local
registry call remains as a rolling-deploy compatibility nudge.'
operationId: stop_conversation_stream_api_v1_chat_conversations__conversation_id__stop_post
security:
- HTTPBearer: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
format: uuid
title: Conversation Id
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/chat/conversations/{conversation_id}/stream:
get:
tags:
- chat
summary: Resume Message Stream
description: 'Re-attach to an in-flight chat-stream producer.
Replays the durable turn snapshot and then tails live events, regardless of
which API worker accepted or executes the turn. Legacy process-local
sessions remain as a rolling-deploy fallback.'
operationId: resume_message_stream_api_v1_chat_conversations__conversation_id__stream_get
security:
- HTTPBearer: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
format: uuid
title: Conversation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/chat/conversations/{conversation_id}/turns/{turn_id}/stream:
get:
tags:
- chat
summary: Stream Durable Turn
description: Replay and live-tail one explicit durable turn.
operationId: stream_durable_turn_api_v1_chat_conversations__conversation_id__turns__turn_id__stream_get
security:
- HTTPBearer: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
format: uuid
title: Conversation Id
- name: turn_id
in: path
required: true
schema:
type: string
format: uuid
title: Turn Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/chat/transcribe:
post:
tags:
- chat
summary: Transcribe Audio
description: 'Transcribe a short voice recording from the chat composer.
Forwards the uploaded audio blob to OpenAI''s transcription API and
returns the recognised text. The frontend records via MediaRecorder
(webm/opus on Chromium, mp4 on Safari), so we accept the common
browser audio MIMEs.'
operationId: transcribe_audio_api_v1_chat_transcribe_post
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_transcribe_audio_api_v1_chat_transcribe_post'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/v1/chat/conversations/{conversation_id}/messages:
post:
tags:
- chat
summary: Send Message
description: 'Send a user message and stream the assistant response via SSE.
Accepts multipart/form-data with a text content field and optional image files.
Saves the user message, then streams the LLM response as Server-Sent Events.
The final message_complete event contains the saved assistant message.'
operationId: send_message_api_v1_chat_conversations__conversation_id__messages_post
security:
- HTTPBearer: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
format: uuid
title: Conversation Id
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_send_message_api_v1_chat_conversations__conversation_id__messages_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/chat/executor-health:
get:
tags:
- chat
summary: Chat Executor Health
description: 'Operational health of the durable chat execution pool.
This endpoint is intentionally separate from the API task''s load-balancer
readiness: removing healthy API tasks cannot repair a missing executor.
Operators get an explicit 503 while accepted turns remain safely queued.'
operationId: chat_executor_health_api_v1_chat_executor_health_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
security:
- HTTPBearer: []
/api/v1/chat/conversations/{conversation_id}/turns:
post:
tags:
- chat
summary: Accept Conversation Turn
description: Accept a turn durably; observation happens through its stream URL.
operationId: accept_conversation_turn_api_v1_chat_conversations__conversation_id__turns_post
security:
- HTTPBearer: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
format: uuid
title: Conversation Id
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_accept_conversation_turn_api_v1_chat_conversations__conversation_id__turns_post'
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChatTurnAccepted'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/chat/conversations/turns:
post:
tags:
- chat
summary: Create Conversation With Turn
description: Atomically create a conversation, its first message, and its turn.
operationId: create_conversation_with_turn_api_v1_chat_conversations_turns_post
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_create_conversation_with_turn_api_v1_chat_conversations_turns_post'
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChatTurnAccepted'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/v1/chat/conversations/{conversation_id}/execute-task:
post:
tags:
- chat
summary: Execute Task
description: 'Execute a task from a chat conversation.
Creates a Run and starts orchestrated execution in the background.'
operationId: execute_task_api_v1_chat_conversations__conversation_id__execute_task_post
security:
- HTTPBearer: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
format: uuid
title: Conversation Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExecuteTaskRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ExecuteTaskResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/chat/conversations/{conversation_id}/apply-kb-edits:
post:
tags:
- chat
summary: Apply Kb Edits
description: Apply KB edits proposed in a kb_edit_proposal chat message.
operationId: apply_kb_edits_api_v1_chat_conversations__conversation_id__apply_kb_edits_post
security:
- HTTPBearer: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
format: uuid
title: Conversation Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApplyKBEditsRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ApplyKBEditsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/chat/conversations/{conversation_id}/proposals/{message_id}/accept:
post:
tags:
- chat
summary: Accept Proposal
description: Accept an agent-builder proposal, apply it, and resume the builder turn.
operationId: accept_proposal_api_v1_chat_conversations__conversation_id__proposals__message_id__accept_post
security:
- HTTPBearer: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
format: uuid
title: Conversation Id
- name: message_id
in: path
required: true
schema:
type: string
format: uuid
title: Message Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptProposalRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/chat/conversations/{conversation_id}/proposals/{message_id}/refuse:
post:
tags:
- chat
summary: Refuse Proposal
description: 'Refuse an agent-builder proposal and resume the builder turn so it can
revise (optionally informed by the user''s comment).'
operationId: refuse_proposal_api_v1_chat_conversations__conversation_id__proposals__message_id__refuse_post
security:
- HTTPBearer: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
format: uuid
title: Conversation Id
- name: message_id
in: path
required: true
schema:
type: string
format: uuid
title: Message Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RefuseProposalRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
ApplyKBEditsRequest:
properties:
message_id:
type: string
format: uuid4
title: Message Id
type: object
required:
- message_id
title: ApplyKBEditsRequest
RefuseProposalRequest:
properties:
comment:
anyOf:
- type: string
- type: 'null'
title: Comment
type: object
title: RefuseProposalRequest
ChatConversationListResponse:
properties:
conversations:
items:
$ref: '#/components/schemas/ChatConversationResponse'
type: array
title: Conversations
total:
type: integer
title: Total
page:
type: integer
title: Page
page_size:
type: integer
title: Page Size
type: object
required:
- conversations
- total
- page
- page_size
title: ChatConversationListResponse
AcceptProposalRequest:
properties:
execution_mode:
anyOf:
- type: string
- type: 'null'
title: Execution Mode
type: object
title: AcceptProposalRequest
Body_create_conversation_with_turn_api_v1_chat_conversations_turns_post:
properties:
content:
type: string
title: Content
default: ''
execution_mode:
type: string
title: Execution Mode
default: cloud
images:
items:
type: string
contentMediaType: application/octet-stream
type: array
title: Images
default: []
files:
items:
type: string
contentMediaType: application/octet-stream
type: array
title: Files
default: []
file_paths:
items:
type: string
type: array
title: File Paths
default: []
tagged_agent_id:
anyOf:
- type: string
- type: 'null'
title: Tagged Agent Id
type: object
title: Body_create_conversation_with_turn_api_v1_chat_conversations_turns_post
MessageType:
type: string
enum:
- general
- system
- planning
- task_suggestion
- task_execution
- task_result
- tool_call
- run_question
- user_question
- kb_answer
- kb_edit_proposal
- agent_builder_proposal
- agent_created
- trigger_created
- workflow_created
- workflow_updated
- plan_update
title: MessageType
Body_send_message_api_v1_chat_conversations__conversation_id__messages_post:
properties:
content:
type: string
title: Content
default: ''
execution_mode:
type: string
title: Execution Mode
default: cloud
images:
items:
type: string
contentMediaType: application/octet-stream
type: array
title: Images
default: []
files:
items:
type: string
contentMediaType: application/octet-stream
type: array
title: Files
default: []
file_paths:
items:
type: string
type: array
title: File Paths
default: []
type: object
title: Body_send_message_api_v1_chat_conversations__conversation_id__messages_post
UsedIntegration:
properties:
app_slug:
type: string
title: App Slug
invocation_count:
type: integer
title: Invocation Count
type: object
required:
- app_slug
- invocation_count
title: UsedIntegration
description: A connector the chat agent actually invoked in a conversation.
Body_transcribe_audio_api_v1_chat_transcribe_post:
properties:
audio:
type: string
contentMediaType: application/octet-stream
title: Audio
type: object
required:
- audio
title: Body_transcribe_audio_api_v1_chat_transcribe_post
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
LinkedTaskRef:
properties:
id:
type: string
format: uuid4
title: Id
title:
type: string
title: Title
status:
type: string
title: Status
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unisson/refs/heads/main/openapi/unisson-chat-api-openapi.yml