---
title: "Update a session"
method: POST
path: "/v1/sessions"
tags: ["Sessions"]
---

# Update a session

`POST /v1/sessions`

## Headers

- `Notion-Version` '2026-03-11', required

## Request body

- union — Exactly one mode: append a message, answer pending actions, or replay from an event.
  - object
    - `message` string, required
    - `agent_id` union
      - string
      - 'notion_ai' | '33333333-3333-3333-3333-333333333333' — One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`
    - `session_id` string
    - `attachments` object[]
      - `file_upload` object, required
        - `id` string, required
      - `type` 'file_upload' — Always `file_upload`
      - `name` string
    - `metadata` object
    - `prompt_context` string
  - object
    - `session_id` string, required
    - `actions` object[], required
      - `action_id` string, required
      - `option_id` 'approve' | 'reject', required — One of: `approve`, `reject`
    - `metadata` object
  - object
    - `session_id` string, required
    - `continue_from` string, required

## Response `200`

- object
  - `object` 'session', required — Always `session`
  - `id` string, required
  - `agent_id` string, required
  - `title` string, required
  - `status` 'queued' | 'in_progress' | 'requires_action' | 'completed' | 'failed' | 'canceled' | 'terminated', required — One of: `queued`, `in_progress`, `requires_action`, `completed`, `failed`, `canceled`, `terminated`
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `required_actions` object[]
    - `action_id` string, required
    - `title` string, required
    - `options` object[], required
      - `id` 'approve' | 'reject', required — One of: `approve`, `reject`
      - `label` string, required
  - `error` object
    - `code` string, required
    - `message` string, required
    - `retryable` boolean, required

## Other responses

- `400`
- `401`
- `403`
- `404`
- `406`
- `409`
- `429`
- `500`
- `503`
- `504`
- `529`

---

[API](https://skmtc.net/notion/apis/notion-api.md) · [All operations](https://skmtc.net/notion/apis/notion-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/notion/notion-api/revisions/dee5763763b0/schema)