> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/api-reference/readme/platform/sessions.md).

# 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://platform.api-us.concurrence.com","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"}}]}}}}
```

## Agones fleet capacity status

> Live Agones fleet capacity for the per-call voice fleet: Ready/Allocated/total GameServers plus headroom against the maxReplicas ceiling. Workspace-GLOBAL — one fleet serves every workspace, so the path workspace\_id is only the auth anchor, never a data filter. Operator-only.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"FleetStatusResponse":{"properties":{"fleet":{"type":"string","title":"Fleet"},"namespace":{"type":"string","title":"Namespace"},"ready":{"type":"integer","title":"Ready"},"allocated":{"type":"integer","title":"Allocated"},"total":{"type":"integer","title":"Total"},"max_replicas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Replicas"},"headroom":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Headroom"},"by_state":{"additionalProperties":{"type":"integer"},"type":"object","title":"By State"}},"type":"object","required":["fleet","namespace","ready","allocated","total","max_replicas","headroom","by_state"],"title":"FleetStatusResponse","description":"Live Agones fleet capacity (workspace-global).\n\n``headroom`` = remaining isolated-unit slots (``max_replicas - allocated``);\n``max_replicas``/``headroom`` are null when the ceiling isn't configured upstream.\nThe counts span the whole fleet (one fleet serves every workspace) — this is NOT\nper-workspace. ``fleet``/``namespace`` echo which fleet was read."}}},"paths":{"/v1/{workspace_id}/sessions/fleet-status":{"get":{"tags":["Sessions"],"summary":"Agones fleet capacity status","description":"Live Agones fleet capacity for the per-call voice fleet: Ready/Allocated/total GameServers plus headroom against the maxReplicas ceiling. Workspace-GLOBAL — one fleet serves every workspace, so the path workspace_id is only the auth anchor, never a data filter. Operator-only.","operationId":"get_fleet_status_v1__workspace_id__sessions_fleet_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FleetStatusResponse"}}}}},"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://platform.api-us.concurrence.com","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://platform.api-us.concurrence.com","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_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."},"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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/api-reference/readme/platform/sessions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.