--- title: "Chat" method: POST path: "/v1/agent_sessions/{session_id}/chat" tags: ["chat"] --- # Chat `POST /v1/agent_sessions/{session_id}/chat` ## Path parameters - `session_id` string, required ## Request body - ChatRequestBody — Assistant chat submit request payload. - `headless` boolean, required — Whether a headless client (terminal or scripted) is driving the turn, as opposed to the browser assistant. Selects the agent configuration the turn runs on. - `contexts` ChatContext[] - union — Discriminated union of every UI-state context the agent understands. - AppContext — Per-turn browser clock context for resolving relative time requests. - `type` 'app', required - `currentDateTime` string, required - `timeZone` string, required - ProjectContext — Project the user is currently viewing. ``span_filter`` carries the project-scoped span filter expression when the span filter field is mounted — empty string when the field is mounted with no condition applied, ``None`` when the field is not present at all. It describes the view in full, root-span scoping included (which is expressed within the filter DSL as ``parent_id is None``). - `type` 'project', required - `projectNodeId` string, required - `spanFilter` string, nullable - TraceContext - `type` 'trace', required - `projectNodeId` string, required - `otelTraceId` string, required - SessionContext — Session the user is currently viewing. - `type` 'session', required - `projectNodeId` string, required - `sessionNodeId` string, required - PromptContext — Prompt the user is currently viewing. - `type` 'prompt', required - `promptNodeId` string, required - PromptVersionContext — Prompt version the user is currently viewing. - `type` 'prompt_version', required - `promptNodeId` string, required - `promptVersionNodeId` string, required - AgentSpanContext — Span the user has selected. Exactly one of ``span_node_id`` (relay) or ``otel_span_id`` (OpenTelemetry hex) must be set. ``project_node_id`` is optional because a span can be selected from views outside a project route. - `type` 'span', required - `projectNodeId` string, nullable - `spanNodeId` string, nullable - `otelSpanId` string, nullable - PlaygroundContext — Playground prompt editor state mounted in the current browser route. - `type` 'playground', required - `recordExperiments` boolean - `repetitions` integer - `nextExperimentScaffold` PlaygroundExperimentScaffoldContext — Experiment name/description/metadata the user has staged for the playground's *next* dataset-backed run, before that run has started. The playground UI lets the user pre-set how the next recorded run's experiment will be named, described, and tagged (via the ``set_playground_experiment_recording`` tool or the recording form). That staged state is surfaced here so the agent can see what is already set and avoid re-staging it. Field semantics: - ``name`` / ``description``: the staged values, surfaced to the model verbatim, or ``None`` when the user has not staged them. - ``has_metadata``: a presence flag, not the value. Only *whether* metadata has been staged is model-relevant (so the agent knows not to re-attach it); the metadata object itself is deliberately kept out of the prompt. A field left unstaged (``None`` / ``False``) falls back to the server default when the run starts. The scaffold is consumed once that next run begins. - `name` string, nullable - `description` string, nullable - `hasMetadata` boolean - `instances` PlaygroundInstanceContext[] - `instanceId` integer, required - `model` union - PlaygroundBuiltinModelContext — Built-in playground model selection. - … - PlaygroundCustomProviderModelContext — Custom-provider playground model selection. - … - `experimentId` string, nullable - `evaluators` PlaygroundEvaluatorContext[] - `datasetEvaluatorId` string, required - `name` string, required - `kind` 'LLM' | 'CODE' | 'BUILTIN', required - `isBuiltin` boolean, required - `isApplied` boolean, required - CodeEvaluatorContext — Code-evaluator create/edit form mounted in the current browser route. - `type` 'code_evaluator', required - `evaluatorNodeId` string, nullable - LlmEvaluatorContext — LLM-evaluator create/edit form mounted in the current browser route. - `type` 'llm_evaluator', required - `evaluatorNodeId` string, nullable - DatasetContext — Dataset the user is currently viewing or has bound to a workflow. Carries the dataset's relay node id and, when known, the active version node id. These IDs scope the create-form handoff link and the sampling of active dataset examples used as prompt context; the dataset schema itself is open. - `type` 'dataset', required - `datasetNodeId` string, required - `datasetVersionNodeId` string, nullable - GraphQLContext — GraphQL runtime state. - `type` 'graphql', required - `mutationsEnabled` boolean, required - WebAccessContext — User's per-turn request to expose web search / fetch tools. - `type` 'web_access', required - `enabled` boolean, required - SubagentsContext — User's per-turn request to expose the subagent-spawning tool. - `type` 'subagents', required - `enabled` boolean, required - `editPermission` 'manual' | 'bypass' - `requestedSkills` string[] — Skills the user explicitly requested via the prompt's slash-command affordance. The server force-loads each available skill by injecting a synthetic load_skill tool call/result at the tail of the message history. Unknown or context-unavailable names are ignored. - `model` union, required - CustomProviderModelSelection — Chat against a stored custom provider record. - `providerType` 'custom', required - `providerId` string, required - `modelName` string, required - BuiltInProviderModelSelection — Chat against a Phoenix built-in provider. Credentials and connection details (base URL, Azure endpoint, AWS region) are resolved from the secret store first and the process environment second. - `providerType` 'builtin', required - `provider` 'OPENAI' | 'AZURE_OPENAI' | 'ANTHROPIC' | 'GOOGLE' | 'DEEPSEEK' | 'XAI' | 'OLLAMA' | 'AWS' | 'CEREBRAS' | 'FIREWORKS' | 'GROQ' | 'MOONSHOT' | 'PERPLEXITY' | 'TOGETHER', required - `modelName` string, required - `trigger` 'submit-message' - `id` string, required - `message` PhoenixUIMessage — ``UIMessage`` with metadata narrowed to the Phoenix wire shapes. - `id` string, required - `role` 'system' | 'user' | 'assistant', required - `metadata` MessageMetadata — ``UIMessage.metadata`` as a registry of namespaces. - `phoenix` union - PhoenixAssistantMessageMetadata — The ``phoenix`` metadata namespace of an assistant message. - `type` 'assistant', required - `sessionId` string, required - `turnTraceContext` TurnTraceContext — The trace identity a turn's spans are parented to. - `traceId` string, required - `rootSpanId` string, required - `startedAt` string, date-time, required - `usage` AssistantMessageMetadataUsage - `tokens` AssistantMessageMetadataUsageTokens, required - … - `promptDetails` AssistantMessageMetadataUsageCacheTokenDetails — Prompt-cache token counts, mounted as the usage payload's ``prompt_details`` because cached tokens are a breakdown of the prompt. - … - `interrupted` boolean - PhoenixUserMessageMetadata — The ``phoenix`` metadata namespace the browser attaches to outgoing user messages. - `type` 'user', required - `currentDateTime` string, required - `timeZone` string, required - `isCompactionMessage` boolean - `pydantic_ai` PydanticAIMessageMetadata — Local pin of pydantic-ai's message-level ``pydantic_ai`` metadata namespace (its private ``_PydanticAIMessageMetadata``), merged into the assistant metadata by the stream's metadata chunk. - `timestamp` string, date-time, nullable - `parts` union[], required - union - TextUIPart — A text part of a message. - `type` 'text' - `text` string, required - `state` 'streaming' | 'done', nullable - `providerMetadata` object, nullable - ReasoningUIPart — A reasoning part of a message. - `type` 'reasoning' - `text` string, required - `state` 'streaming' | 'done', nullable - `providerMetadata` object, nullable - ToolInputStreamingPart — Tool part in input-streaming state. - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'input-streaming' - `input` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - ToolInputAvailablePart — Tool part in input-available state. - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'input-available' - `input` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - PhoenixDbTypesDataStreamProtocolRequestTypesToolOutputAvailablePart — Tool part in output-available state. - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-available' - `input` unknown - `output` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `preliminary` boolean, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - PhoenixDbTypesDataStreamProtocolRequestTypesToolOutputErrorPart — Tool part in output-error state. - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-error' - `input` unknown - `rawInput` unknown - `errorText` string, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - ToolApprovalRequestedPart — Tool part in approval-requested state (awaiting user decision). - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'approval-requested' - `input` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - ToolApprovalRespondedPart — Tool part in approval-responded state (user approved/denied, execution pending). - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'approval-responded' - `input` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - ToolOutputDeniedPart — Tool part in output-denied state (tool was denied, terminal state). - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-denied' - `input` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - DynamicToolInputStreamingPart — Dynamic tool part in input-streaming state. - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'input-streaming' - `input` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - DynamicToolInputAvailablePart — Dynamic tool part in input-available state. - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'input-available' - `input` unknown, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - PhoenixDbTypesDataStreamProtocolRequestTypesDynamicToolOutputAvailablePart — Dynamic tool part in output-available state. - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-available' - `input` unknown, required - `output` unknown, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `preliminary` boolean, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - PhoenixDbTypesDataStreamProtocolRequestTypesDynamicToolOutputErrorPart — Dynamic tool part in output-error state. - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-error' - `input` unknown, required - `errorText` string, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - DynamicToolApprovalRequestedPart — Dynamic tool part in approval-requested state (awaiting user decision). - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'approval-requested' - `input` unknown, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - DynamicToolApprovalRespondedPart — Dynamic tool part in approval-responded state (user approved/denied, execution pending). - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'approval-responded' - `input` unknown, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - DynamicToolOutputDeniedPart — Dynamic tool part in output-denied state (tool was denied, terminal state). - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-denied' - `input` unknown, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - SourceUrlUIPart — A source part of a message. - `type` 'source-url' - `sourceId` string, required - `url` string, required - `title` string, nullable - `providerMetadata` object, nullable - SourceDocumentUIPart — A document source part of a message. - `type` 'source-document' - `sourceId` string, required - `mediaType` string, required - `title` string, required - `filename` string, nullable - `providerMetadata` object, nullable - FileUIPart — A file part of a message. - `type` 'file' - `mediaType` string, required - `filename` string, nullable - `url` string, required - `providerMetadata` object, nullable - DataUIPart — Data part with dynamic type based on data name. - `type` string, required - `id` string, nullable - `data` unknown, required - StepStartUIPart — A step boundary part of a message. - `type` 'step-start' - `toolOutputs` union[] — Client-executed tool results for pending tool calls on the transcript's trailing assistant message, matched by ``toolCallId``. Submitted alone they continue the assistant turn; submitted with ``message`` they resolve dangling tool calls before the new user turn runs. - union - PhoenixDbTypesDataStreamProtocolRequestTypesToolOutputAvailablePart — Tool part in output-available state. - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-available' - `input` unknown - `output` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `preliminary` boolean, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - `id` string, required - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - `id` string, required - `approved` boolean, required - `reason` string, nullable - PhoenixDbTypesDataStreamProtocolRequestTypesToolOutputErrorPart — Tool part in output-error state. - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-error' - `input` unknown - `rawInput` unknown - `errorText` string, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - `id` string, required - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - `id` string, required - `approved` boolean, required - `reason` string, nullable - PhoenixDbTypesDataStreamProtocolRequestTypesDynamicToolOutputAvailablePart — Dynamic tool part in output-available state. - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-available' - `input` unknown, required - `output` unknown, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `preliminary` boolean, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - `id` string, required - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - `id` string, required - `approved` boolean, required - `reason` string, nullable - PhoenixDbTypesDataStreamProtocolRequestTypesDynamicToolOutputErrorPart — Dynamic tool part in output-error state. - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-error' - `input` unknown, required - `errorText` string, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - `id` string, required - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - `id` string, required - `approved` boolean, required - `reason` string, nullable - `lastMessageId` string, nullable — The id of the last transcript message the client has rendered, used for optimistic concurrency. Omit when the session has no messages; required (and validated against the persisted transcript) once it does. On mismatch the server rejects the send with HTTP 409 and code ``agent_session_messages_stale`` — the client should refetch the session before retrying. - `recordLocalTraces` boolean - `exportRemoteTraces` boolean - `instrumentUserId` boolean — When true and the request is authenticated as a PhoenixUser, attaches the user's email as the OpenInference ``user.id`` span attribute on all traced work for this request. ## Response `200` Successful Response - unknown ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `409` — The request conflicts with the session's current state; the body's ``code`` field says how. - `422` — Validation Error - `507` — Insufficient Storage --- [API](https://skmtc.net/arize-ai/apis/arize-phoenix-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-phoenix-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-phoenix-rest-api/revisions/8ac3f55fbe00/schema)