Sessions API: Create, List, Fork, and Manage Sessions

Sessions are the core resource in the Omnigent API. Each session represents a live agent conversation with its own message history, sub-agent children, file resources, terminals, and code environments. Sessions are bound to an agent spec (which determines the harness, model, and available tools) and to a runner (a Python subprocess that executes the LLM loop). You interact with a session by posting events and subscribing to its SSE stream.

List Sessions

GET /v1/sessions Returns a cursor-paginated list of sessions. Only sessions with an agent binding are included — legacy conversations without an agent are excluded. Query parameters:

limit

integer

default:"20"

Maximum sessions to return. Range: 1–1000.

after

string

Cursor — return sessions whose ID appears after this value in sort order.

before

string

Cursor — return sessions before this ID.

agent_id

string

Filter to sessions bound to a specific agent, e.g. "ag_abc123".

agent_name

string

Filter by bound agent name. Includes session-scoped agents sharing the name.

order

string

default:"desc"

Sort direction. "desc" (newest first) or "asc" (oldest first).

sort_by

string

default:"created_at"

Column to sort on. "created_at" or "updated_at".

search_query

string

Case-insensitive substring filter on the session title or conversation content.

include_archived

boolean

default:"false"

When true, includes archived sessions alongside active ones.

kind

string

default:"default"

Conversation kind: "default" (user-initiated), "sub_agent", or "any".

Response — PaginatedList:

{
  "object": "list",
  "data": [
    {
      "id": "conv_abc123",
      "agent_id": "ag_xyz",
      "status": "idle",
      "title": "Debug auth flow",
      "created_at": 1700000000,
      "updated_at": 1700001000
    }
  ],
  "first_id": "conv_abc123",
  "last_id": "conv_abc123",
  "has_more": false
}

Create Session

POST /v1/sessions Creates a new session. Accepts either JSON (bind to an already-registered agent by ID) or multipart/form-data (upload an agent bundle and create in one request). JSON request body:

agent_id

string

Identifier of a registered agent to bind, e.g. "ag_abc123".

title

string

Optional human-readable title, e.g. "debugging auth flow".

labels

object

Initial guardrails labels, e.g. {"env": "prod"}.

reasoning_effort

string

Per-session reasoning effort hint: "none", "low", "medium", "high", "max".

host_id

string

Optional host to launch the runner on, e.g. "host_a1b2c3".

workspace

string

Absolute path on the host to use as the runner’s working directory, e.g. "/Users/alice/projects/api".

git

object

Optional git worktree options. When set the server creates a worktree for a new branch off workspace.

Show git fields

branch_name

string

required

Name of the new branch to create, e.g. "feature/login".

base_branch

string

Base ref to branch from, e.g. "main". Defaults to HEAD.

Response — 201 Created with the full session snapshot.

Get Session

GET /v1/sessions/{session_id} Returns the full snapshot of a session, including committed items, status, and resource references. Path parameter: session_id — the session/conversation identifier. Query parameters:

include_items

boolean

default:"true"

When false, skips the conversation items read and returns items: []. Useful when you load items separately via the paginated items endpoint.

include_liveness

boolean

default:"true"

When false, skips runner/host liveness checks and returns those fields as null.

Response fields:

string

Session/conversation identifier, e.g. "conv_abc123".

agent_id

string

Durable identifier of the bound agent.

agent_name

string

Human-readable name of the bound agent.

status

string

Lifecycle status: "idle", "running", "waiting", or "failed".

created_at

integer

Unix epoch timestamp of creation.

title

string

Optional human-readable title.

labels

object

Session-scoped guardrails labels.

runner_id

string

Runner currently bound to this session, or null.

runner_online

boolean

Whether the runner has an open WebSocket tunnel, or null when include_liveness=false.

items

array

Committed conversation items in chronological order. Empty when include_items=false.

Update Session

PATCH /v1/sessions/{session_id} Updates mutable session fields. All fields are optional — omitted fields are left unchanged.

title

string

New session title.

runner_id

string

Bind or rebind to a registered runner. Last-write-wins.

labels

object

Labels to upsert. Merges with existing labels; unmentioned keys are untouched.

reasoning_effort

string

Per-session reasoning effort. Use "default" to clear back to the agent’s setting.

model_override

string

Override the agent’s configured LLM model, e.g. "claude-opus-4-7". Use "default" to clear.

archived

boolean

true archives (hides from the default listing); false unarchives.

Delete Session

DELETE /v1/sessions/{session_id} Deletes a session and all associated resources: tasks, runner-side environments and terminals, session files, and the conversation row. Requires owner-level access. Query parameter: delete_branch (boolean, default false) — when true and the session has a server-created git worktree, the host also removes the worktree directory and deletes its branch.

Fork Session

POST /v1/sessions/{source_id}/fork Deep-copies a session’s conversation items into a new session. Useful for branching a conversation to try a different approach.

title

string

Title for the forked session. Defaults to "Fork of <source_title>".

agent_id

string

Switch the fork to a different built-in agent, e.g. to fork a Claude session into Codex.

up_to_response_id

string

Truncation point. When set, only history up to and including this response is copied.

Response — 201 Created with the new session snapshot.

Post Event

POST /v1/sessions/{session_id}/events Submits an input event to a session. Dispatches on type:

`type`	Behaviour
`"message"`	Persists a user message and starts or steers a turn
`"interrupt"`	Cancels the active turn and publishes `session.interrupted`
`"approval"`	Resolves an outstanding elicitation in-band
`"compact"`	Triggers explicit context compaction

type

string

required

Event discriminator, e.g. "message".

data

object

Type-specific payload. For "message": {"role": "user", "content": [{"type": "input_text", "text": "Hello"}]}.

model_override

string

Optional per-event LLM model override for the resulting turn.

Response — 202 Accepted:

{ "queued": true, "item_id": "item_abc123" }

For control events ("interrupt", "approval"): { "queued": false }.

List Conversation Items

GET /v1/sessions/{session_id}/items Lists persisted conversation items with cursor-based pagination.

limit

integer

default:"100"

Maximum items to return. Range: 1–1000.

after

string

Cursor — return items after this item ID.

order

string

default:"asc"

Sort order: "asc" (chronological) or "desc".

List Child Sessions

GET /v1/sessions/{session_id}/child_sessions Lists sub-agent sessions spawned under this parent session.

limit

integer

default:"20"

Maximum children to return.

after

string

Forward pagination cursor.

order

string

default:"desc"

Sort direction.

Switch Agent

POST /v1/sessions/{session_id}/switch-agent Rebinds an existing session to a different agent harness in place. The transcript, files, comments, and workspace are kept; only the agent/harness changes.

agent_id

string

required

Built-in agent to switch to, e.g. "ag_builtin_codex". Must be a built-in agent listed by GET /v1/agents.

Python SDK

from omnigent_client import OmnigentClient

async with OmnigentClient(base_url="http://localhost:6767") as client:

    # List sessions
    sessions = await client.sessions.list()

    # Get a single session snapshot
    session = await client.sessions.get("conv_abc123")

    # Fork a session
    fork_data = await client.sessions.fork(
        "conv_abc123",
        title="My fork",
        up_to_response_id="resp_xyz",
    )

    # Post a user message
    await client.sessions.post_event(
        "conv_abc123",
        {
            "type": "message",
            "data": {
                "role": "user",
                "content": [{"type": "input_text", "text": "Hello!"}],
            },
        },
    )

    # Interrupt a running turn
    await client.sessions.interrupt("conv_abc123")

    # Compact conversation history
    await client.sessions.compact("conv_abc123")

    # Bind a runner
    updated = await client.sessions.bind_runner(
        "conv_abc123", runner_id="runner_def456"
    )

    # List conversation items
    items = await client.sessions.list_items("conv_abc123")

Overview

Sessions

Hosts & Runners

Resources

Sessions API: Create, List, Fork, and Manage Sessions

List Sessions

Create Session

Get Session

Update Session

Delete Session

Fork Session

Post Event

List Conversation Items

List Child Sessions

Switch Agent

Python SDK

Build docs developers (and LLMs) love

Overview

Sessions

Hosts & Runners

Resources

Documentation Index

​List Sessions

​Create Session

​Get Session

​Update Session

​Delete Session

​Fork Session

​Post Event

​List Conversation Items

​List Child Sessions

​Switch Agent

​Python SDK

Build docs developers (and LLMs) love

List Sessions

Create Session

Get Session

Update Session

Delete Session

Fork Session

Post Event

List Conversation Items

List Child Sessions

Switch Agent

Python SDK