# Sessions

## List active voice sessions

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"ActiveSession":{"properties":{"call_sid":{"type":"string","title":"Call Sid"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workspace Id"},"caller_id":{"type":"string","title":"Caller Id"},"direction":{"type":"string","title":"Direction"},"duration_seconds":{"type":"number","title":"Duration Seconds"},"current_state":{"type":"string","title":"Current State","default":""},"scenario":{"type":"string","title":"Scenario","default":""}},"type":"object","required":["call_sid","caller_id","direction","duration_seconds"],"title":"ActiveSession"}}},"paths":{"/v1/{workspace_id}/sessions/active":{"get":{"tags":["Sessions"],"summary":"List active voice sessions","description":"Real-time list of active voice sessions from Valkey (cross-pod).","operationId":"list_active_sessions_v1__workspace_id__sessions_active_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ActiveSession"},"type":"array","title":"Response List Active Sessions V1  Workspace Id  Sessions Active Get"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Inject event into active session

> 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.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"InjectRequest":{"properties":{"message":{"type":"string","maxLength":5000,"minLength":1,"title":"Message"},"sender":{"type":"string","maxLength":200,"title":"Sender","default":"System"},"event_type":{"type":"string","enum":["external_event","guidance"],"title":"Event Type","description":"external_event (factual info) or guidance (instructional)","default":"external_event"}},"type":"object","required":["message"],"title":"InjectRequest"},"InjectResponse":{"properties":{"status":{"type":"string","enum":["delivered","queued_no_subscriber"],"title":"Status"},"call_sid":{"type":"string","title":"Call Sid"}},"type":"object","required":["status","call_sid"],"title":"InjectResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/v1/{workspace_id}/sessions/{call_sid}/inject":{"post":{"tags":["Sessions"],"summary":"Inject event into active session","description":"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.","operationId":"inject_session_event_v1__workspace_id__sessions__call_sid__inject_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"call_sid","in":"path","required":true,"schema":{"type":"string","title":"Call Sid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InjectRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InjectResponse"}}}},"404":{"description":"Session not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"503":{"description":"Voice agent service unavailable."}}}}}}
```

## Start a web text conversation session with an entity

> 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.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"StartSessionRequest":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"World model entity UUID. Provide either entity_id or canonical_id."},"canonical_id":{"anyOf":[{"$ref":"#/components/schemas/CanonicalIdString"},{"type":"null"}],"description":"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 table; a freshly-created entity may not be visible yet if the projection is lagging. Provide either entity_id or canonical_id, not both."},"channel_kind":{"type":"string","const":"web","title":"Channel Kind"},"greeting":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Greeting","description":"Custom greeting. Agent auto-greets if omitted."}},"type":"object","required":["service_id","channel_kind"],"title":"StartSessionRequest"},"CanonicalIdString":{"type":"string","maxLength":256,"minLength":3,"pattern":"^[A-Za-z0-9._-]+:[A-Za-z0-9._-]+:[A-Za-z0-9._-]+$"},"StartSessionResponse":{"properties":{"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id"},"session_status":{"type":"string","enum":["created","already_active"],"title":"Session Status"},"channel_kind":{"type":"string","const":"web","title":"Channel Kind"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["conversation_id","session_status","channel_kind","entity_id","service_id","created_at"],"title":"StartSessionResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/v1/{workspace_id}/sessions/start":{"post":{"tags":["Sessions"],"summary":"Start a web text conversation session with an entity","description":"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.","operationId":"start_text_session_v1__workspace_id__sessions_start_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSessionRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSessionResponse"}}}},"404":{"description":"Service or entity not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"503":{"description":"Agent service unavailable."}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme/platform/sessions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.