Atmee.aiDocs
APIAPI referenceAvatar sessions

End an avatar session (optional explicit stop)

POST
/v1/avatar_sessions/{id}/end

Ends either kind of API session; for a conversation, POST /v1/sessions/{id}/end with an API key is the same call. It settles completed with endReason: ended_by_api, never failed.

Stops billing for the session now. Idempotent: ending a session that already ended answers 200 with alreadyEnded: true, so the plugin can call it from every teardown path without checking first. The primary end signal is the rendering worker's own report when your agent leaves, the room closes, or you remove the avatar participant — this call is the fallback for a worker that could not report, and the way to stop paying for an avatar you are done with while your room stays open. For a render it does not remove the avatar from your room; remove the participant yourself (the plugin does so on close). A conversation's room is closed, as by POST /v1/sessions/{id}/end. Acts only on sessions started through the API (the account's website sessions are 404), and for an avatar-scoped key only on its avatar's.

Authorization

headerX-Api-Key<token>

Secret embed API key (sk_atmee_...; keys minted before 2026-09 carry sk_live_...), held by the customer's own backend and never sent to a browser. Format: X-Api-Key: sk_atmee_....

Path Parameters

id*string

The avatar session id (sessionId from the create response).

Formatuuid

Response Body

The session is ended (or already was).

application/json
  1. response
sessionId*string
Formatuuid
status*string
Value in"completed""failed"
endedAt?string
Formatdate-time
alreadyEnded*boolean

True when the session was already terminal before this call.

endReason?string

Why the session ended: ended_by_api for this call, or the earlier reason when it had already ended (see AvatarSessionStatusResponse.endReason).

Example Request
curl -X POST 'https://api.atmanity.us/v1/avatar_sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/end'
Example Response
{  "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",  "status": "completed",  "endedAt": "2019-08-24T14:15:22Z",  "alreadyEnded": true,  "endReason": "string"}

Read a session's state, end reason and cost GET

Reads either kind of API session: a conversation (POST /v1/sessions, kind: conversation) or a render into your own room (POST /v1/avatar_sessions, kind: render).

Start a speech-to-speech session (audio only, no video) POST

Reserves a speech session with an avatar: a realtime speech-to-speech conversation over a WebSocket, without video.

End an avatar session (optional explicit stop) — Atmee Docs