--- title: "Run Headless Agent" method: POST path: "/agents/server/sessions/{session_id}/chat" tags: ["chat"] deprecated: true --- # Run Headless Agent `POST /agents/server/sessions/{session_id}/chat` > **Deprecated.** ## Path parameters - `session_id` string, required ## Request body - union — Discriminated union of legacy chat request payloads. - LegacyChatSubmitMessage — Submit message extended with Phoenix-specific fields. - `trigger` 'submit-message' - `id` string, required - `messages` LegacyAssistantMetadataUIMessage[], required - `id` string, required - `role` 'system' | 'user' | 'assistant', required - `metadata` LegacyAssistantMessageMetadata — Legacy transcripts predate the ``type`` discriminator, so default it here. - `type` 'assistant' - `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 - `prompt` integer, required - `completion` integer, required - `total` integer, required - `promptDetails` AssistantMessageMetadataUsageCacheTokenDetails — Prompt-cache token counts, mounted as the usage payload's ``prompt_details`` because cached tokens are a breakdown of the prompt. - `cacheRead` integer, required - `cacheWrite` integer, required - `interrupted` boolean - `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' - `id` string, nullable - `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 - … - 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 - … - PydanticAiUiVercelAiRequestTypesToolOutputAvailablePart — 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 - `preliminary` boolean, nullable - `approval` union - … - PydanticAiUiVercelAiRequestTypesToolOutputErrorPart — 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 - `approval` union - … - 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 - … - 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 - … - 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 - … - 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 - … - 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 - … - PydanticAiUiVercelAiRequestTypesDynamicToolOutputAvailablePart — 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 - `preliminary` boolean, nullable - `approval` union - … - PydanticAiUiVercelAiRequestTypesDynamicToolOutputErrorPart — 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 - `approval` union - … - 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 - … - 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 - … - 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 - … - 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' - `ingestTraces` boolean - `exportRemoteTraces` boolean - `attachUserId` 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. - `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 - ProjectUIContext - `type` 'project', required - `projectNodeId` string, required - `spanFilter` string, nullable - TraceUIContext - `type` 'trace', required - `projectNodeId` string, required - `otelTraceId` string, required - SessionUIContext - `type` 'session', required - `projectNodeId` string, required - `sessionNodeId` string, required - PromptUIContext - `type` 'prompt', required - `promptNodeId` string, required - PromptVersionUIContext - `type` 'prompt_version', required - `promptNodeId` string, required - `promptVersionNodeId` string, required - SpanUIContext - `type` 'span', required - `projectNodeId` string, nullable - `spanNodeId` string, nullable - `otelSpanId` string, nullable - PlaygroundUIContext - `type` 'playground', required - `recordExperiments` boolean - `repetitions` integer - `nextExperimentScaffold` PlaygroundExperimentScaffoldUIContext - `name` string, nullable - `description` string, nullable - `hasMetadata` boolean - `instances` PlaygroundInstanceUIContext[] - `instanceId` integer, required - `model` union - … - `experimentId` string, nullable - `evaluators` PlaygroundEvaluatorUIContext[] - `datasetEvaluatorId` string, required - `name` string, required - `kind` 'LLM' | 'CODE' | 'BUILTIN', required - `isBuiltin` boolean, required - `isApplied` boolean, required - CodeEvaluatorUIContext - `type` 'code_evaluator', required - `evaluatorNodeId` string, nullable - LlmEvaluatorUIContext - `type` 'llm_evaluator', required - `evaluatorNodeId` string, nullable - DatasetUIContext - `type` 'dataset', required - `datasetNodeId` string, required - `datasetVersionNodeId` string, nullable - GraphQLContext — Deprecated GraphQL mutations opt-in. - `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. Ignored by this legacy route. - `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 - LegacyChatRegenerateMessage — Regenerate message extended with Phoenix-specific fields. - `trigger` 'regenerate-message', required - `id` string, required - `messages` LegacyAssistantMetadataUIMessage[], required - `id` string, required - `role` 'system' | 'user' | 'assistant', required - `metadata` LegacyAssistantMessageMetadata — Legacy transcripts predate the ``type`` discriminator, so default it here. - `type` 'assistant' - `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 - `prompt` integer, required - `completion` integer, required - `total` integer, required - `promptDetails` AssistantMessageMetadataUsageCacheTokenDetails — Prompt-cache token counts, mounted as the usage payload's ``prompt_details`` because cached tokens are a breakdown of the prompt. - `cacheRead` integer, required - `cacheWrite` integer, required - `interrupted` boolean - `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' - `id` string, nullable - `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 - … - 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 - … - PydanticAiUiVercelAiRequestTypesToolOutputAvailablePart — 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 - `preliminary` boolean, nullable - `approval` union - … - PydanticAiUiVercelAiRequestTypesToolOutputErrorPart — 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 - `approval` union - … - 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 - … - 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 - … - 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 - … - 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 - … - 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 - … - PydanticAiUiVercelAiRequestTypesDynamicToolOutputAvailablePart — 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 - `preliminary` boolean, nullable - `approval` union - … - PydanticAiUiVercelAiRequestTypesDynamicToolOutputErrorPart — 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 - `approval` union - … - 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 - … - 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 - … - 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 - … - 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' - `messageId` string, nullable - `ingestTraces` boolean - `exportRemoteTraces` boolean - `attachUserId` 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. - `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 - ProjectUIContext - `type` 'project', required - `projectNodeId` string, required - `spanFilter` string, nullable - TraceUIContext - `type` 'trace', required - `projectNodeId` string, required - `otelTraceId` string, required - SessionUIContext - `type` 'session', required - `projectNodeId` string, required - `sessionNodeId` string, required - PromptUIContext - `type` 'prompt', required - `promptNodeId` string, required - PromptVersionUIContext - `type` 'prompt_version', required - `promptNodeId` string, required - `promptVersionNodeId` string, required - SpanUIContext - `type` 'span', required - `projectNodeId` string, nullable - `spanNodeId` string, nullable - `otelSpanId` string, nullable - PlaygroundUIContext - `type` 'playground', required - `recordExperiments` boolean - `repetitions` integer - `nextExperimentScaffold` PlaygroundExperimentScaffoldUIContext - `name` string, nullable - `description` string, nullable - `hasMetadata` boolean - `instances` PlaygroundInstanceUIContext[] - `instanceId` integer, required - `model` union - … - `experimentId` string, nullable - `evaluators` PlaygroundEvaluatorUIContext[] - `datasetEvaluatorId` string, required - `name` string, required - `kind` 'LLM' | 'CODE' | 'BUILTIN', required - `isBuiltin` boolean, required - `isApplied` boolean, required - CodeEvaluatorUIContext - `type` 'code_evaluator', required - `evaluatorNodeId` string, nullable - LlmEvaluatorUIContext - `type` 'llm_evaluator', required - `evaluatorNodeId` string, nullable - DatasetUIContext - `type` 'dataset', required - `datasetNodeId` string, required - `datasetVersionNodeId` string, nullable - GraphQLContext — Deprecated GraphQL mutations opt-in. - `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. Ignored by this legacy route. - `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 ## Response `200` Successful Response - unknown ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — Validation Error - `507` — Insufficient Storage ## Changes - **2026-08-28** `4016becf04d6` — 2 info - added the new optional request property `oneOf[subschema #1: LegacyChatSubmitMessage]/messages/items/parts/items/anyOf[subschema #2: ReasoningUIPart]/id` - added the new optional request property `oneOf[subschema #2: LegacyChatRegenerateMessage]/messages/items/parts/items/anyOf[subschema #2: ReasoningUIPart]/id` - …earlier changes not shown [Full history](https://skmtc.dev/arize-ai/apis/arize-phoenix-rest-api/changes/agents/server/sessions/:session_id/chat/post.md) --- [API](https://skmtc.dev/arize-ai/apis/arize-phoenix-rest-api.md) · [All operations](https://skmtc.dev/arize-ai/apis/arize-phoenix-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/arize-ai/arize-phoenix-rest-api/revisions/f440cb6427a5/schema)