Conversations
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
HSM execution channel type.
Determines how the HSM engine communicates with end users. Each kind maps to one or more providers.
webPossible values: Destination address for an outbound conversation (E.164 for sms/imessage). Required for non-web.
Channel-manager use case the outbound conversation is sent through. Required for non-web; channel-manager resolves the sender (FROM) from it (never caller-supplied). Must be owned by this workspace.
Optional context steering what the agent opens with on an outbound conversation.
Outbound thread-keyed channels (sms/imessage) only: close any existing ACTIVE conversation on the computed provider thread (recipient + use case) before dispatching, so the opener materializes a brand-new conversation instead of continuing the old thread. Rejected with 422 on channel=web — every web create already starts a new conversation, so force_new is meaningless there.
falseSuccessful Response
HSM execution channel type.
Determines how the HSM engine communicates with end users. Each kind maps to one or more providers.
0True when the conversation recorded more entries than one read takes (10,000), so the turns stop before the end of the conversation.
falseValidation Error
POST /v1/{workspace_id}/conversations HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 271
{
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"entity_id": "123e4567-e89b-12d3-a456-426614174000",
"channel": "web",
"recipient": "text",
"use_case_id": "123e4567-e89b-12d3-a456-426614174000",
"instruction": "text",
"force_new": false,
"context": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"channel_kind": "voice",
"status": "active",
"lifecycle": "active",
"entity_id": "123e4567-e89b-12d3-a456-426614174000",
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"direction": "text",
"turn_count": 0,
"duration_seconds": 1,
"created_at": "text",
"updated_at": "text",
"call_sid": "text",
"caller_id": "text",
"phone_number": "text",
"quality_score": 1,
"has_recording": true,
"completion_reason": "text",
"escalation_status": "text",
"final_state": "text",
"source": "text",
"turns": [
{
"turn_id": "123e4567-e89b-12d3-a456-426614174000",
"turn_index": 1,
"role": "agent",
"text": "text",
"timestamp": "text",
"channel": "voice",
"content": [
{
"type": "text",
"text": "text",
"url": "text",
"media_type": "text",
"provider_id": "text",
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"tool_calls": [
{
"tool_name": "text",
"call_id": "text",
"input": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"result": "",
"succeeded": true,
"duration_ms": 1,
"error_message": "text"
}
],
"artifacts": [
{
"type": "text",
"schema_version": "text",
"payload": "[Circular Reference]"
}
],
"selected_action_description": "text",
"state_transitions": [
{
"from": "text",
"to": "text"
}
],
"available_actions": [
{
"description": "text"
}
]
}
],
"truncated": false,
"plan": "text",
"voice": {
"recording_path": "text",
"twilio_recording_sid": "text",
"twilio_recording_duration": 1,
"has_recording": false,
"emotional_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"barge_in_events": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"states_visited": [
"text"
],
"participants": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"config": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"call_analysis": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"forwarding": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"escalation": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"safety": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"quality_breakdown": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"risk_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"latency_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"conversation_metrics": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"tool_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"safety_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"operator_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}Move an active conversation onto a different channel (sms/imessage today). The durable conversation id is preserved — the same conversation continues; only its routing changes. Optionally dispatch a first agent turn on the new channel.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Target channel to move the conversation to (sms or imessage).
Recipient address on the new channel (E.164). Required for sms/imessage.
Channel-manager use case for the new channel (resolves the sender). Required for sms/imessage.
Why the conversation is being moved (e.g. escalation, customer_request).
If true, immediately drive one agent turn on the new channel (e.g. 'I'll text you now').
falseOptional context steering the opener when dispatch_opener=true.
Successful Response
HSM execution channel type.
Determines how the HSM engine communicates with end users. Each kind maps to one or more providers.
0True when the conversation recorded more entries than one read takes (10,000), so the turns stop before the end of the conversation.
falseValidation Error
POST /v1/{workspace_id}/conversations/{conversation_id}/channel HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 152
{
"channel": "voice",
"recipient": "text",
"use_case_id": "123e4567-e89b-12d3-a456-426614174000",
"reason": "text",
"dispatch_opener": false,
"instruction": "text"
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"channel_kind": "voice",
"status": "active",
"lifecycle": "active",
"entity_id": "123e4567-e89b-12d3-a456-426614174000",
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"direction": "text",
"turn_count": 0,
"duration_seconds": 1,
"created_at": "text",
"updated_at": "text",
"call_sid": "text",
"caller_id": "text",
"phone_number": "text",
"quality_score": 1,
"has_recording": true,
"completion_reason": "text",
"escalation_status": "text",
"final_state": "text",
"source": "text",
"turns": [
{
"turn_id": "123e4567-e89b-12d3-a456-426614174000",
"turn_index": 1,
"role": "agent",
"text": "text",
"timestamp": "text",
"channel": "voice",
"content": [
{
"type": "text",
"text": "text",
"url": "text",
"media_type": "text",
"provider_id": "text",
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"tool_calls": [
{
"tool_name": "text",
"call_id": "text",
"input": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"result": "",
"succeeded": true,
"duration_ms": 1,
"error_message": "text"
}
],
"artifacts": [
{
"type": "text",
"schema_version": "text",
"payload": "[Circular Reference]"
}
],
"selected_action_description": "text",
"state_transitions": [
{
"from": "text",
"to": "text"
}
],
"available_actions": [
{
"description": "text"
}
]
}
],
"truncated": false,
"plan": "text",
"voice": {
"recording_path": "text",
"twilio_recording_sid": "text",
"twilio_recording_duration": 1,
"has_recording": false,
"emotional_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"barge_in_events": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"states_visited": [
"text"
],
"participants": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"config": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"call_analysis": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"forwarding": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"escalation": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"safety": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"quality_breakdown": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"risk_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"latency_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"conversation_metrics": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"tool_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"safety_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"operator_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Include per-turn tool_calls[] in the returned turns. Off by default so the payload stays small and (potentially PHI-bearing) tool output is opt-in, matching POST /turns?include_tool_calls=true.
falseSuccessful Response
HSM execution channel type.
Determines how the HSM engine communicates with end users. Each kind maps to one or more providers.
0True when the conversation recorded more entries than one read takes (10,000), so the turns stop before the end of the conversation.
falseValidation Error
GET /v1/{workspace_id}/conversations/{conversation_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"channel_kind": "voice",
"status": "active",
"lifecycle": "active",
"entity_id": "123e4567-e89b-12d3-a456-426614174000",
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"direction": "text",
"turn_count": 0,
"duration_seconds": 1,
"created_at": "text",
"updated_at": "text",
"call_sid": "text",
"caller_id": "text",
"phone_number": "text",
"quality_score": 1,
"has_recording": true,
"completion_reason": "text",
"escalation_status": "text",
"final_state": "text",
"source": "text",
"turns": [
{
"turn_id": "123e4567-e89b-12d3-a456-426614174000",
"turn_index": 1,
"role": "agent",
"text": "text",
"timestamp": "text",
"channel": "voice",
"content": [
{
"type": "text",
"text": "text",
"url": "text",
"media_type": "text",
"provider_id": "text",
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"tool_calls": [
{
"tool_name": "text",
"call_id": "text",
"input": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"result": "",
"succeeded": true,
"duration_ms": 1,
"error_message": "text"
}
],
"artifacts": [
{
"type": "text",
"schema_version": "text",
"payload": "[Circular Reference]"
}
],
"selected_action_description": "text",
"state_transitions": [
{
"from": "text",
"to": "text"
}
],
"available_actions": [
{
"description": "text"
}
]
}
],
"truncated": false,
"plan": "text",
"voice": {
"recording_path": "text",
"twilio_recording_sid": "text",
"twilio_recording_duration": 1,
"has_recording": false,
"emotional_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"barge_in_events": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"states_visited": [
"text"
],
"participants": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"config": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"call_analysis": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"forwarding": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"escalation": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"safety": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"quality_breakdown": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"risk_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"latency_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"conversation_metrics": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"tool_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"safety_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"operator_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
No content
Validation Error
DELETE /v1/{workspace_id}/conversations/{conversation_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Page through the turns GET /conversations/{conversation_id} returns, ordered by exchange (turn_index). The default +turn_index starts with the messages before the first user turn; -turn_index starts with the newest exchange and ends with them. Messages inside one exchange keep conversation order either way. Turns are folded from the conversation's journal on each request rather than read from a table, so truncated matches the detail's flag. When it is true, the turns stop at the read bound, before the end of the conversation, in either sort order.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
[]50Include per-turn tool_calls[] in the returned turns. Off by default, matching GET /conversations/{conversation_id}?include_tool_calls=true.
falseSuccessful Response
True when the conversation recorded more entries than one read takes (10,000), so the turns stop before the end of the conversation.
Validation Error
GET /v1/{workspace_id}/conversations/{conversation_id}/turns HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"turn_id": "123e4567-e89b-12d3-a456-426614174000",
"turn_index": 1,
"role": "agent",
"text": "text",
"timestamp": "text",
"channel": "voice",
"content": [
{
"type": "text",
"text": "text",
"url": "text",
"media_type": "text",
"provider_id": "text",
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"tool_calls": [
{
"tool_name": "text",
"call_id": "text",
"input": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"result": "",
"succeeded": true,
"duration_ms": 1,
"error_message": "text"
}
],
"artifacts": [
{
"type": "text",
"schema_version": "text",
"payload": "[Circular Reference]"
}
],
"selected_action_description": "text",
"state_transitions": [
{
"from": "text",
"to": "text"
}
],
"available_actions": [
{
"description": "text"
}
]
}
],
"has_more": true,
"continuation_token": null,
"truncated": true
}Send a user message and receive the agent's response. Set Accept: text/event-stream to receive an SSE stream of typed TurnStreamEvent frames (token, tool_call_started, tool_call_completed, thinking, message, done, error) instead of the synchronous JSON response. For new integrations prefer POST /turns/stream, which is always SSE.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Include tool call details in response
falsePoll for a background result without sending a user message. Protocol v2 claims at most one ready answer and returns an opaque delivery receipt; render or durably persist the answer, then acknowledge that receipt. Returns empty output when nothing is ready. Must NOT be combined with a request-body message (422) or SSE streaming (422). Poll no more than once every ~5s per conversation.
falseStable UUID for replaying the same logical send or poll after an ambiguous failure. Reuse the same value only for that operation. Omission is backward-compatible but cannot provide client-controlled response-loss replay.
The user's message. Leave it empty (with no content or media) only to kick off a conversation that has no turns yet: the agent answers with its greeting. Once the conversation has a turn, a turn with no user input is a 422.
""Injected into the agent's prompt as caller/patient context for this turn.
Synchronous callers only: when a turn hands work to a background tool (background_pending), await the real answer inline (bounded, ~30s) instead of returning the acknowledgement immediately. On completion the response carries the final answer with background_pending=false; on timeout it returns background_pending=true — resolve it later with poll=true. null (default) inherits the channel policy (web = do not wait). Ignored with poll=true (422).
Synchronous callers only: when a turn ends background_pending, omit the filler/acknowledgement text from output so a batch caller never mistakes the ack for the answer (output is empty; background_pending=true is the poll-later signal). null (default) inherits the channel policy. Ignored with poll=true (422).
Successful Response
Identifier of the user exchange this turn created — or, for poll=true and greeting-kickoff turns (empty message), the exchange the returned messages attach to. A background delivery keeps the originating exchange even when later user turns already exist. Deterministic: matches the turn_id on this conversation's history turns, so it can anchor durable per-turn artifacts (e.g. feedback) across page reloads. Null only when the conversation has no user exchange yet (a poll or kickoff before the first user message).
Whether this turn's output is the final answer, or only an acknowledgement that
work is still running in the background.
false (default): output is the complete agent response for this turn.
true: a tool crossed the server's blocking window and was handed to a background
task, so output is NOT the final answer — the definitive assistant answer is
produced later, out-of-band. Under delivery protocol v2, collect it by re-issuing
POST …/turns with poll=true (a no-message, receipt-backed claim), render or
durably persist the returned answer, then acknowledge its exact delivery receipt.
This is the per-conversation delivery contract — see
the web-integration paved path. (GET /v1/{workspace_id}/events/stream?conversation_id=
mirrors this activity as text.tool_started / text.background_result /
text.agent_message for a view watching this one conversation, but is not the
per-chat delivery path. The stream without conversation_id carries none of it.) A
client that treats a background_pending=true turn as complete without polling and
acknowledging will miss the final answer.
falseVersion of the durable background-delivery protocol supported by the serving agent. Clients may retry polls only after observing version 2.
Validation Error
POST /v1/{workspace_id}/conversations/{conversation_id}/turns HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 300
{
"message": "",
"content": [
{
"type": "text",
"text": "text",
"url": "text",
"media_type": "text",
"provider_id": "text",
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"media_url": "text",
"media_type": "text",
"context": "text",
"viewport_width": 1,
"viewport_height": 1,
"wait_for_final": true,
"suppress_filler": true
}{
"turn_id": "123e4567-e89b-12d3-a456-426614174000",
"input": {
"turn_id": "123e4567-e89b-12d3-a456-426614174000",
"turn_index": 1,
"role": "agent",
"text": "text",
"timestamp": "text",
"channel": "voice",
"content": [
{
"type": "text",
"text": "text",
"url": "text",
"media_type": "text",
"provider_id": "text",
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"tool_calls": [
{
"tool_name": "text",
"call_id": "text",
"input": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"result": "",
"succeeded": true,
"duration_ms": 1,
"error_message": "text"
}
],
"artifacts": [
{
"type": "text",
"schema_version": "text",
"payload": {
"ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
}
}
],
"selected_action_description": "text",
"state_transitions": [
{
"from": "text",
"to": "text"
}
],
"available_actions": [
{
"description": "text"
}
]
},
"output": [
{
"turn_id": "123e4567-e89b-12d3-a456-426614174000",
"turn_index": 1,
"role": "agent",
"text": "text",
"timestamp": "text",
"channel": "voice",
"content": [
{
"type": "text",
"text": "text",
"url": "text",
"media_type": "text",
"provider_id": "text",
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"tool_calls": [
{
"tool_name": "text",
"call_id": "text",
"input": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"result": "",
"succeeded": true,
"duration_ms": 1,
"error_message": "text"
}
],
"artifacts": [
{
"type": "text",
"schema_version": "text",
"payload": {
"ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
}
}
],
"selected_action_description": "text",
"state_transitions": [
{
"from": "text",
"to": "text"
}
],
"available_actions": [
{
"description": "text"
}
]
}
],
"tool_calls": [
{
"tool_name": "text",
"call_id": "text",
"input": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"result": "",
"succeeded": true,
"duration_ms": 1,
"error_message": "text"
}
],
"artifacts": [
{
"type": "text",
"schema_version": "text",
"payload": {
"ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
}
}
],
"conversation": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "active",
"turn_count": 0,
"updated_at": "text",
"context_graph_state": {
"type": "text",
"name": "text",
"objective": "text",
"actions": [
{
"description": "text",
"filler_hint": "text"
}
],
"intra_state_navigation_guidelines": [
"text"
],
"action_guidelines": [
"text"
],
"boundary_constraints": [
"text"
],
"exit_conditions": [
{
"description": "text",
"next_state": "text",
"filler_hint": "text"
}
],
"action_tool_call_specs": [
{
"tool_id": "text",
"additional_instruction": "",
"navigate_on_completion": false,
"progress": {
"deterministic": false,
"phrases": [
"text"
],
"trigger_delay_ms": 1,
"interval_ms": 1,
"mode": "auto",
"progress_class": "lookup",
"expected_latency_ms": 1,
"custom_phrase": "text"
},
"result_persistence": "accumulate",
"delivery": "interrupt",
"failure_delivery": "interrupt",
"failure_delivery_by_class": {
"ANY_ADDITIONAL_PROPERTY": "interrupt"
},
"execution": "blocking",
"lifecycle": "independent",
"context_bindings": [
"text"
],
"context_binding_aliases": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"audio_fillers": [
"text"
],
"audio_filler_triggered_after": 1
}
],
"exit_condition_tool_call_specs": [
{
"tool_id": "text",
"additional_instruction": "",
"navigate_on_completion": false,
"progress": {
"deterministic": false,
"phrases": [
"text"
],
"trigger_delay_ms": 1,
"interval_ms": 1,
"mode": "auto",
"progress_class": "lookup",
"expected_latency_ms": 1,
"custom_phrase": "text"
},
"result_persistence": "accumulate",
"delivery": "interrupt",
"failure_delivery": "interrupt",
"failure_delivery_by_class": {
"ANY_ADDITIONAL_PROPERTY": "interrupt"
},
"execution": "blocking",
"lifecycle": "independent",
"context_bindings": [
"text"
],
"context_binding_aliases": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"audio_fillers": [
"text"
],
"audio_filler_triggered_after": 1
}
],
"wait_for": "surface_submission",
"guardrails": [
{
"name": "text",
"description": "text",
"enforcement": "hard"
}
],
"channel_overrides": {
"ANY_ADDITIONAL_PROPERTY": {
"objective": "text",
"action_guidelines": [
"text"
],
"progress": {
"deterministic": false,
"phrases": [
"text"
],
"trigger_delay_ms": 1,
"interval_ms": 1,
"mode": "auto",
"progress_class": "lookup",
"expected_latency_ms": 1,
"custom_phrase": "text"
}
}
},
"surface_spec_template": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"turn_policy": {
"barge_in_enabled": true,
"safety_response": "stay_empathize",
"context_strategy": "full",
"degradation_threshold": -1,
"block_forward_call": false,
"block_forward_call_after_turns": -1,
"stt_eot_threshold": 1,
"stt_eager_eot_threshold": 1,
"stt_eot_timeout_ms": 1
},
"preload": [
{
"tool_id": "text",
"params": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
]
}
},
"background_pending": false,
"delivery": {
"delivery_id": "123e4567-e89b-12d3-a456-426614174000",
"request_id": "123e4567-e89b-12d3-a456-426614174000",
"receipt": "123e4567-e89b-12d3-a456-426614174000"
},
"delivery_protocol_version": 1
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
No content
Validation Error
POST /v1/{workspace_id}/conversations/{conversation_id}/turns/{delivery_id}/ack HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 102
{
"request_id": "123e4567-e89b-12d3-a456-426614174000",
"receipt": "123e4567-e89b-12d3-a456-426614174000"
}No content
Streaming variant of POST /turns. Always returns text/event-stream regardless of the Accept header — no JSON fallback. Each frame is a TurnStreamEvent discriminated by the event field (token, tool_call_started, tool_call_completed, thinking, message, done, error). Use this endpoint for new integrations; the Accept-sniffing variant remains for backward compatibility.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Include tool_call_started / tool_call_completed frames in the stream
falseStable UUID for replaying the same logical streamed user-input turn.
The user's message. Leave it empty (with no content or media) only to kick off a conversation that has no turns yet: the agent answers with its greeting. Once the conversation has a turn, a turn with no user input is a 422.
""Injected into the agent's prompt as caller/patient context for this turn.
Synchronous callers only: when a turn hands work to a background tool (background_pending), await the real answer inline (bounded, ~30s) instead of returning the acknowledgement immediately. On completion the response carries the final answer with background_pending=false; on timeout it returns background_pending=true — resolve it later with poll=true. null (default) inherits the channel policy (web = do not wait). Ignored with poll=true (422).
Synchronous callers only: when a turn ends background_pending, omit the filler/acknowledgement text from output so a batch caller never mistakes the ack for the answer (output is empty; background_pending=true is the poll-later signal). null (default) inherits the channel policy. Ignored with poll=true (422).
SSE stream of TurnStreamEvent frames
Conversation or service not found
Conversation is closed
Conversation is missing or has corrupt service binding
Agent service unavailable
POST /v1/{workspace_id}/conversations/{conversation_id}/turns/stream HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 300
{
"message": "",
"content": [
{
"type": "text",
"text": "text",
"url": "text",
"media_type": "text",
"provider_id": "text",
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"media_url": "text",
"media_type": "text",
"context": "text",
"viewport_width": 1,
"viewport_height": 1,
"wait_for_final": true,
"suppress_filler": true
}No content
Lets the external user who owns a conversation approve or reject a write that the agent paused for their confirmation. Only the conversation's own external user may call this; it requires the conversations:approve_own scope.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
An external user's decision on a parked, approval-gated write in their own conversation.
Successful Response
No content
Not an external_user token, or missing conversations:approve_own scope
Conversation not found or not owned by the caller
Validation Error
Decision store temporarily unavailable — safe to retry
POST /v1/{workspace_id}/conversations/{conversation_id}/approval HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 38
{
"decision": "approve",
"reason": "text"
}No content
Last updated
Was this helpful?