Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Sessions

List active voice sessions

get

Real-time list of active voice sessions from Valkey (cross-pod).

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Responses
200

Successful Response

application/json
call_sidstringRequired
service_idstring · uuid · nullableOptional
workspace_idstring · uuid · nullableOptional
caller_idstringRequired
directionstringRequired
duration_secondsnumberRequired
current_statestringOptionalDefault: ""
scenariostringOptionalDefault: ""
get/v1/{workspace_id}/sessions/active
GET /v1/{workspace_id}/sessions/active HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Successful Response

[
  {
    "call_sid": "text",
    "service_id": "123e4567-e89b-12d3-a456-426614174000",
    "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
    "caller_id": "text",
    "direction": "text",
    "duration_seconds": 1,
    "current_state": "",
    "scenario": ""
  }
]

Agones fleet capacity status

get

Live Agones fleet capacity: Ready/Allocated/total GameServers plus headroom against the maxReplicas ceiling. fleet=voice (default) reads the per-call voice fleet; fleet=tool-runner reads the isolated background-tool fleet. Workspace-GLOBAL — one fleet serves every workspace, so the path workspace_id is only the auth anchor, never a data filter. Operator-only.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Query parameters
fleetstring · enumOptionalDefault: voicePossible values:
Responses
200

Successful Response

application/json

Live Agones fleet capacity (workspace-global).

headroom = remaining isolated-unit slots (max_replicas - allocated); max_replicas/headroom are null when the ceiling isn't configured upstream. The counts span the whole fleet (one fleet serves every workspace) — this is NOT per-workspace. fleet/namespace echo which fleet was read (voice per-call fleet, or the tool-runner background-tool fleet via ?fleet=tool-runner).

fleetstringRequired
namespacestringRequired
readyintegerRequired
allocatedintegerRequired
totalintegerRequired
max_replicasinteger · nullableRequired
headroominteger · nullableRequired
get/v1/{workspace_id}/sessions/fleet-status
GET /v1/{workspace_id}/sessions/fleet-status HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "fleet": "text",
  "namespace": "text",
  "ready": 1,
  "allocated": 1,
  "total": 1,
  "max_replicas": 1,
  "headroom": 1,
  "by_state": {
    "ANY_ADDITIONAL_PROPERTY": 1
  }
}

Inject event into active session

post

Inject an external event or guidance message into an active voice session. The agent incorporates it into its next response. Use event_type='guidance' for operator coaching, 'external_event' for system notifications.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
call_sidstringRequired
Body
messagestring · min: 1 · max: 5000Required
senderstring · max: 200OptionalDefault: System
event_typestring · enumOptional

external_event (factual info) or guidance (instructional)

Default: external_eventPossible values:
Responses
200

Successful Response

application/json
statusstring · enumRequiredPossible values:
call_sidstringRequired
post/v1/{workspace_id}/sessions/{call_sid}/inject
POST /v1/{workspace_id}/sessions/{call_sid}/inject HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 66

{
  "message": "text",
  "sender": "System",
  "event_type": "external_event"
}
{
  "status": "delivered",
  "call_sid": "text"
}

Start a web text conversation session with an entity

post

Start a web text session with a world model entity. Materializes the conversation and returns conversation_id for subsequent turns via POST /v1/{ws}/conversations/{id}/turns.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body
service_idstring · uuidRequired
entity_idstring · uuid · nullableOptional

World model entity UUID. Provide either entity_id or canonical_id.

canonical_idstring · min: 3 · max: 256 · nullableOptional

World model canonical_id of the form 'source:resource_type:id' (e.g. 'charmhealth:Patient:67890'). The structural regex on CanonicalIdString blocks spaces, names, DOBs, and similar regulated content. Resolved against the SDP-projected world.entities_synced table; a freshly-created entity may not be visible yet if the projection is lagging. Provide either entity_id or canonical_id, not both.

Pattern: ^[A-Za-z0-9._-]+:[A-Za-z0-9._-]+:[A-Za-z0-9._-]+$
channel_kindconst: webRequired
greetingstring · max: 2000 · nullableOptional

Custom greeting. Agent auto-greets if omitted.

Responses
201

Successful Response

application/json
conversation_idstring · uuidRequired
session_statusstring · enumRequiredPossible values:
channel_kindconst: webRequired
entity_idstring · uuidRequired
service_idstring · uuidRequired
created_atstringRequired
post/v1/{workspace_id}/sessions/start
POST /v1/{workspace_id}/sessions/start HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 166

{
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "canonical_id": "text",
  "channel_kind": "text",
  "greeting": "text"
}
{
  "conversation_id": "123e4567-e89b-12d3-a456-426614174000",
  "session_status": "created",
  "channel_kind": "text",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "text"
}
PreviousReview QueueNextOperators

Last updated

Was this helpful?