Create an agent chat
Creates an empty chat owned by the caller, with an optional title, model, and appearance, and returns it. Requires a Clerk session for a workspace member with the `ai:write` permission. The conversation itself is driven by the separate streaming turn route, not by this operation.
apiKeyAuthorizationBearer <snoze_sk_…>Workspace API key created in Workspace settings → API keys. Scopes on the key bound what it can read and write.
workspaceId*stringapplication/json- body
title?string|null|nullmodel?string|null|nullappearance?|nullSuccess
application/json- response
data*curl -X POST 'https://api.snoze.dev/v1/workspaces/string/agent/chats' \ -H 'Content-Type: application/json' \ -d '{}'{ "data": { "id": "string", "workspaceId": "string", "title": "string", "parentSessionId": "string", "model": "string", "appearance": { "shape": "box", "color": "string", "accentColor": "string", "eyes": "dot", "eyePlacement": "centered", "motion": "still", "finish": "flat", "gradientColor": "string", "glowColor": "string", "intensity": "subtle", "cosmetics": { "head": "none", "face": "none" } }, "status": "idle", "runningMessageId": "string", "streamIdentity": { "turnId": "string", "messageId": "string" }, "lastError": "string", "background": { "enabled": true, "continuations": 0, "deadlineAt": 0 }, "createdAt": "string", "updatedAt": "string" }}List the caller's agent chats in a workspace
Returns the chats this user created in the workspace, most recently updated first, with each chat's status, model, appearance, and last error. A chat still marked `running` past the stuck threshold is reaped into `error` while the list is built. Requires a Clerk session for a workspace member with the `ai:read` permission; API keys cannot call this group.
Read an agent chat transcript
Returns the chat, the messages along its currently active thread with their parts, and the chat's plan when it has one. Requires a Clerk session for a workspace member with the `ai:read` permission; a chat that does not exist, or belongs to another user, is reported as not found. Live token output arrives on the separate streaming routes rather than here. The optional candidateTurnId verifies a stable running or terminal launch; recoveryTurnId additionally requires a terminal launch. An unstable or replaced snapshot returns a null streamIdentity and must not select a replacement reader.