> ## Documentation Index > Fetch the complete documentation index at: https://developers.notion.com/llms.txt > Use this file to discover all available pages before exploring further. # Chat with Agent (Streaming) This endpoint is deprecated. Use `POST /v1/agents/{agent_id}/chat` with `Accept: application/x-ndjson` instead. The legacy endpoint remains available for compatibility. This endpoint returns a newline-delimited JSON (NDJSON) stream. Each line is a complete JSON object (a “chunk”). In the OpenAPI renderer, the `application/json` schema represents the shape of a **single chunk**. The actual HTTP response body is `application/x-ndjson` (a stream of these chunks). Notes: * `message` chunks are upserts keyed by `id` (the same message may be emitted multiple times as tool results arrive). * When `verbose=false`, agent `message` chunks omit `content_parts` and only include `content`. * `error` chunks are emitted when the agent encounters a failure during inference. The `code` field contains a programmatic error code (e.g. `internal_server_error`, `rate_limited`, `restricted_resource`) and the `message` field contains a human-readable description. ## OpenAPI ````yaml openapi-undocumented.json POST /v1/agents/{agent_id}/chatStream openapi: 3.1.0 info: title: Notion API (Undocumented) version: 1.0.0 description: >- Internal/undocumented Notion API endpoints. These endpoints are not part of the public API and may change without notice. Do not rely on these for production integrations. termsOfService: >- https://notion.notion.site/Terms-and-Privacy-28ffdd083dc3473e9c2da6ec011b58ac x-noIndex: true servers: - url: https://api.notion.com security: - bearerAuth: [] tags: - name: Internal description: Internal/undocumented endpoints x-hidden: true paths: /v1/agents/{agent_id}/chatStream: post: tags: - Internal summary: Chat with agent (streaming) operationId: chat-with-agent-stream parameters: - name: agent_id in: path required: true schema: oneOf: - $ref: '#/components/schemas/idRequest' - type: string enum: - notion_ai - 33333333-3333-3333-3333-333333333333 description: 'One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`' description: >- The ID of the agent to chat with. Use a UUID for custom agents or `notion_ai` for Notion Agent (personal agent); the reserved UUID `33333333-3333-3333-3333-333333333333` remains supported for backward compatibility. - name: verbose in: query schema: type: boolean description: >- Whether to include agent thinking and structured message content parts. Defaults to false. - $ref: '#/components/parameters/notionVersion' requestBody: required: true content: application/json: schema: type: object properties: message: type: string maxLength: 10000 description: The message to send to the agent. attachments: type: array items: type: object properties: file_upload: type: object properties: id: type: string description: >- ID of a FileUpload object that has the status `uploaded`. additionalProperties: false required: - id description: >- ID of a FileUpload object that has the status `uploaded`. type: type: string const: file_upload description: >- The type of the attachment. Only supports "file_upload". name: type: string description: An optional display name override for the attachment. additionalProperties: false required: - file_upload maxItems: 100 description: >- An array of file uploads to attach to this chat turn. Use the File Upload APIs to create uploads and pass their IDs here. metadata: type: object additionalProperties: type: string maxLength: 2000 maxProperties: 20 description: >- Optional caller-provided string metadata persisted with the user message. user_id is used for lifecycle correlation and does not change authorization. prompt_context: type: string maxLength: 10000 description: >- Additional caller-provided context for the agent to consider while responding. thread_id: $ref: '#/components/schemas/idRequest' description: >- The ID of an existing thread to continue the conversation. If not provided, a new thread will be created. additionalProperties: false responses: '200': description: '' content: application/json: schema: oneOf: - type: object properties: type: type: string const: message description: Always `message` invocation_id: type: string id: $ref: '#/components/schemas/idResponse' role: type: string enum: - user - agent description: 'One of: `user`, `agent`' content: type: string delta: type: string description: >- Text appended since the previous chunk for this message. Empty for metadata-only updates. If previously emitted text is revised, this contains the full current text. The cumulative `content` field remains authoritative. attachments: type: array items: type: object properties: name: type: string content_type: type: string url: type: string expiry_time: type: string format: date-time description: The time when the attachment URL will expire. additionalProperties: false required: - name - content_type - url maxItems: 100 content_parts: type: array items: oneOf: - type: object properties: type: type: string const: text description: Always `text` text: type: string additionalProperties: false required: - type - text - type: object properties: type: type: string const: thinking description: Always `thinking` text: type: string additionalProperties: false required: - type - text - type: object properties: type: type: string const: tool_call description: Always `tool_call` tool_call_id: oneOf: - type: string - type: 'null' tool_name: type: string results: type: array items: type: object properties: id: $ref: '#/components/schemas/idResponse' agent_step_id: oneOf: - $ref: '#/components/schemas/idResponse' - type: 'null' tool_call_id: oneOf: - type: string - type: 'null' tool_name: type: string tool_type: type: string state: type: string started_at: type: integer minimum: 0 finished_at: oneOf: - type: integer minimum: 0 - type: 'null' duration_ms: oneOf: - type: integer minimum: 0 - type: 'null' additionalProperties: false required: - id - agent_step_id - tool_call_id - tool_name - tool_type - state - started_at - finished_at - duration_ms maxItems: 100 additionalProperties: false required: - type - tool_call_id - tool_name - type: object properties: type: type: string const: follow_ups description: Always `follow_ups` follow_ups: type: array items: type: object properties: label: type: string message: type: string additionalProperties: false required: - label - message maxItems: 100 additionalProperties: false required: - type - follow_ups - type: object properties: type: type: string const: custom_agent_template_picker description: Always `custom_agent_template_picker` additionalProperties: false required: - type maxItems: 100 additionalProperties: false required: - type - invocation_id - id - role - content - delta title: Message - type: object properties: type: type: string const: tool description: Always `tool` invocation_id: type: string id: $ref: '#/components/schemas/idResponse' category: type: string enum: - search - read - write - compute - other description: >- Stable, coarse category suitable for displaying progress without exposing internal tool details. status: type: string enum: - pending - running - waiting_for_user - completed - failed description: >- One of: `pending`, `running`, `waiting_for_user`, `completed`, `failed` agent_step_id: oneOf: - $ref: '#/components/schemas/idResponse' - type: 'null' tool_call_id: oneOf: - type: string - type: 'null' tool_name: type: string tool_type: type: string additionalProperties: false required: - type - invocation_id - id - category - status title: Tool - type: object properties: type: type: string const: started description: Always `started` invocation_id: type: string thread_id: $ref: '#/components/schemas/idResponse' agent_id: type: string description: >- The agent identifier. The personal agent is always `notion_ai`; custom-agent IDs are UUIDs. model: type: string description: >- Configured model identifier, or `auto` when model routing has not resolved yet. metadata: type: object additionalProperties: type: string maxLength: 2000 description: >- Caller-provided string metadata echoed from the chat request. user_id is the lifecycle correlation key and does not change authorization. additionalProperties: false required: - type - invocation_id - thread_id - agent_id - model title: Started - type: object properties: type: type: string const: done description: Always `done` invocation_id: type: string status: type: string enum: - completed - requires_action - canceled description: 'One of: `completed`, `requires_action`, `canceled`' thread_id: $ref: '#/components/schemas/idResponse' model: type: string usage: type: object properties: total_tokens: type: integer minimum: 0 additionalProperties: false required: - total_tokens duration_ms: type: integer minimum: 0 connections_used: type: array items: type: string maxItems: 100 artifacts: type: array items: oneOf: - type: object properties: type: type: string const: page description: Always `page` url: type: string title: type: string additionalProperties: false required: - type - url - title - type: object properties: type: type: string const: html_artifact description: Always `html_artifact` url: type: string page_url: type: string additionalProperties: false required: - type - url - page_url title: Chat stream artifact maxItems: 100 metadata: type: object additionalProperties: type: string maxLength: 2000 description: >- Caller-provided string metadata echoed from the chat request. user_id is the lifecycle correlation key and does not change authorization. pending_user_actions: type: array items: type: object properties: id: $ref: '#/components/schemas/idResponse' type: type: string const: tool_confirmation description: Always `tool_confirmation` title: type: string requirements: type: array items: oneOf: - type: object properties: type: type: string const: general description: Always `general` additionalProperties: false required: - type - type: object properties: type: type: string const: manage_workers description: Always `manage_workers` additionalProperties: false required: - type - type: object properties: type: type: string const: url_safety description: Always `url_safety` urls: type: array items: type: string maxItems: 100 required_by_workspace_policy: type: boolean additionalProperties: false required: - type - urls - type: object properties: type: type: string const: permission_escalation description: Always `permission_escalation` destination_title: type: string source_titles: type: array items: type: string maxItems: 100 additionalProperties: false required: - type - type: object properties: type: type: string const: delete_content description: Always `delete_content` page_count: type: integer minimum: 0 database_count: type: integer minimum: 0 meeting_notes_block_count: type: integer minimum: 0 additionalProperties: false required: - type - page_count - database_count - type: object properties: type: type: string const: connect_integration description: Always `connect_integration` integration_type: type: string integration_name: type: string handoff_url: type: string additionalProperties: false required: - type - integration_type - integration_name - handoff_url - type: object properties: type: type: string const: admin_mode description: Always `admin_mode` explanation: type: string additionalProperties: false required: - type title: Pending user action requirement maxItems: 100 options: type: array items: oneOf: - type: object properties: id: type: string const: approve description: Always `approve` label: type: string additionalProperties: false required: - id - label - type: object properties: id: type: string const: reject description: Always `reject` label: type: string additionalProperties: false required: - id - label - type: object properties: id: type: string const: use_connection description: Always `use_connection` label: type: string input: type: object properties: type: type: string const: connection_id description: Always `connection_id` required: type: boolean const: true description: Always `true` additionalProperties: false required: - type - required additionalProperties: false required: - id - label - input title: Pending user action option maxItems: 100 additionalProperties: false required: - id - type - title - requirements - options maxItems: 100 additionalProperties: false required: - type - invocation_id - status - thread_id - model - usage - duration_ms - connections_used - artifacts title: Done - type: object properties: type: type: string const: waiting_for_user description: Always `waiting_for_user` invocation_id: type: string pending_user_actions: type: array items: type: object properties: id: $ref: '#/components/schemas/idResponse' type: type: string const: tool_confirmation description: Always `tool_confirmation` title: type: string requirements: type: array items: oneOf: - type: object properties: type: type: string const: general description: Always `general` additionalProperties: false required: - type - type: object properties: type: type: string const: manage_workers description: Always `manage_workers` additionalProperties: false required: - type - type: object properties: type: type: string const: url_safety description: Always `url_safety` urls: type: array items: type: string maxItems: 100 required_by_workspace_policy: type: boolean additionalProperties: false required: - type - urls - type: object properties: type: type: string const: permission_escalation description: Always `permission_escalation` destination_title: type: string source_titles: type: array items: type: string maxItems: 100 additionalProperties: false required: - type - type: object properties: type: type: string const: delete_content description: Always `delete_content` page_count: type: integer minimum: 0 database_count: type: integer minimum: 0 meeting_notes_block_count: type: integer minimum: 0 additionalProperties: false required: - type - page_count - database_count - type: object properties: type: type: string const: connect_integration description: Always `connect_integration` integration_type: type: string integration_name: type: string handoff_url: type: string additionalProperties: false required: - type - integration_type - integration_name - handoff_url - type: object properties: type: type: string const: admin_mode description: Always `admin_mode` explanation: type: string additionalProperties: false required: - type title: Pending user action requirement maxItems: 100 options: type: array items: oneOf: - type: object properties: id: type: string const: approve description: Always `approve` label: type: string additionalProperties: false required: - id - label - type: object properties: id: type: string const: reject description: Always `reject` label: type: string additionalProperties: false required: - id - label - type: object properties: id: type: string const: use_connection description: Always `use_connection` label: type: string input: type: object properties: type: type: string const: connection_id description: Always `connection_id` required: type: boolean const: true description: Always `true` additionalProperties: false required: - type - required additionalProperties: false required: - id - label - input title: Pending user action option maxItems: 100 additionalProperties: false required: - id - type - title - requirements - options maxItems: 100 additionalProperties: false required: - type - invocation_id - pending_user_actions title: Waiting for user - type: object properties: type: type: string const: error description: Always `error` code: type: string enum: - invalid_json - invalid_request_url - invalid_request - missing_version - invalid_beta - validation_error - unauthorized - restricted_resource - object_not_found - directory_not_found - rate_limited - service_overload - internal_server_error - service_unavailable - gateway_timeout - conflict_error - idempotency_key_reused - row_limit_exceeded - status_change_not_allowed - agent_deleted - invalid_credit_limit - workspace_credits_exhausted - agent_credit_limit_reached description: >- Programmatic error code. Matches the error codes used by non-streaming Public API endpoints. message: type: string additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string maxItems: 100 invocation_id: type: string description: >- Present after the invocation is accepted; absent for pre-acceptance errors. usage: type: object properties: total_tokens: type: integer minimum: 0 additionalProperties: false required: - total_tokens additionalProperties: false required: - type - code - message title: Error title: Chat stream chunk description: >- A single NDJSON chunk from the chat streaming response. Each line in the stream is one of these chunk types. application/x-ndjson: schema: type: string description: >- Newline-delimited JSON (NDJSON) stream. Each line is a JSON-encoded chunk object. deprecated: true components: schemas: idRequest: type: string idResponse: type: string format: uuid parameters: notionVersion: name: Notion-Version in: header required: true schema: enum: - '2026-03-11' description: >- The [API version](/reference/versioning) to use for this request. The latest version is `2026-03-11`. securitySchemes: bearerAuth: type: http scheme: bearer ````