---
title: "Create session"
method: POST
path: "/api/session"
tags: ["session"]
---

# Create session

`POST /api/session`

## Request

- Base URL: `https://opencode.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://opencode.ai/api/session`
- Auth: none required

Create a session at the requested location. A parentID creates a linked child session at its parent's location.

## Request body

- object
  - `id` string
  - `parentID` string
  - `title` string, nullable
  - `agent` string
  - `model` ModelRef
    - `id` string, required
    - `providerID` string, required
    - `variant` string
  - `location` LocationPublicRef
    - `directory` string, required
  - `metadata` SessionMetadata
  - `permissions` PermissionRule[]
    - `action` string, required
    - `resource` string, required
    - `effect` 'allow' | 'deny' | 'ask', required

## Response `200`

Success

- object
  - `data` SessionInfo, required
    - `id` string, required
    - `parentID` string
    - `fork` object
      - `sessionID` string, required
      - `boundary` union, required
        - object
          - `type` 'before', required
          - `messageID` string, required
        - object
          - `type` 'through', required
          - `messageID` string, required
    - `projectID` string, required
    - `agent` string
    - `model` ModelRef
      - `id` string, required
      - `providerID` string, required
      - `variant` string
    - `cost` number, required
    - `tokens` TokenUsageInfo, required
      - `input` number, required
      - `output` number, required
      - `reasoning` number, required
      - `cache` object, required
        - `read` number, required
        - `write` number, required
    - `outcome` 'succeeded' | 'failed' | 'interrupted'
    - `time` object, required
      - `created` number, required
      - `updated` number, required
      - `idle` number
      - `viewed` number
      - `archived` number
    - `title` string
    - `subpath` string
    - `metadata` SessionMetadata
    - `permissions` PermissionRule[]
      - `action` string, required
      - `resource` string, required
      - `effect` 'allow' | 'deny' | 'ask', required
    - `revert` SessionRevert
      - `messageID` string, required
      - `partID` string
      - `snapshot` string
      - `files` FileDiffInfo[]
        - `file` string, required
        - `patch` string, required
        - `additions` integer, required
        - `deletions` integer, required
        - `status` 'added' | 'deleted' | 'modified', required
        - `more` true
    - `location` LocationPublicRef, required
      - `directory` string, required

## Other responses

- `400`: InvalidRequestError
- `401`: UnauthorizedError
- `404`: SessionNotFoundError

## Changes

> 50 revisions in range; 1 not diffed.

- **2026-10-26** `aa0f65b3d158`: 1 info
  - added the optional property `data/revert/files/items/more` to the response with the `200` status
- **2026-10-24** `1c30ec162e7f`: 1 warning
  - removed the optional property `data/allowance` from the response with the `200` status
- **2026-10-24** `231ec98d2d97`: 1 info
  - added the optional property `data/allowance` to the response with the `200` status

[Operation history](https://skmtc.dev/kaaass/apis/opencode/changes/api/session/post.md)

---

[API](https://skmtc.dev/kaaass/apis/opencode.md) - [All operations](https://skmtc.dev/kaaass/apis/opencode/llms.txt) - [OpenAPI document](https://skmtc.dev/kaaass/apis/opencode/revisions/4e083d954707?raw)