Session Resources API: Files, Terminals, and Environments

Resources are objects attached to a session. Omnigent currently supports three resource types: files (user-uploaded binary artifacts the agent can read), terminals (interactive shell sessions the agent or user can attach to), and environments (sandboxed workspaces with filesystem access, diff support, and shell execution). Resources are created automatically by the runner as the session progresses, or explicitly by the user via upload or launch endpoints.

File resources are binary-safe — they are stored as raw bytes and served back with the original content type. Terminal resources use a WebSocket connection for interactive I/O (not covered by this REST reference — see the WebSocket terminal documentation).

Generic Resource Endpoints

List All Resources

GET /v1/sessions/{session_id}/resources Returns the runner-authoritative resource inventory for a session. Requires the session to be bound to a runner.

type

string

Optional filter by resource type: "environment", "terminal", or "file".

Response — SessionResourcePaginatedList:

{
  "object": "list",
  "data": [
    {
      "id": "default",
      "object": "session.resource",
      "type": "environment",
      "session_id": "conv_abc123",
      "name": "default"
    },
    {
      "id": "terminal_bash_s1",
      "object": "session.resource",
      "type": "terminal",
      "session_id": "conv_abc123",
      "name": "shell",
      "environment": "default"
    }
  ],
  "has_more": false
}

string

Opaque resource identifier, e.g. "default" or "terminal_bash_s1".

object

string

Always "session.resource".

type

string

Resource kind: "environment", "terminal", or "file".

session_id

string

Owning session/conversation identifier.

name

string

Human-readable display name.

metadata

object

Resource-type-specific metadata dict.

environment

string

For terminal resources: the environment ID the terminal runs in. Omitted for non-terminal resources.

Get a Resource by ID

GET /v1/sessions/{session_id}/resources/{resource_id} Returns a single resource by its opaque ID, regardless of type.

File Resources

File resources are user-uploaded binary artifacts stored in the session’s file namespace.

List Session Files

GET /v1/sessions/{session_id}/resources/files

limit

integer

default:"20"

Maximum files to return. Range: 1–1000.

after

string

Forward pagination cursor (file ID).

before

string

Backward pagination cursor.

order

string

default:"desc"

Sort direction: "desc" or "asc".

Upload a File

POST /v1/sessions/{session_id}/resources/files Accepts a multipart/form-data upload. The file is stored under the session’s file namespace and returned as a resource object.

curl -X POST \
  "http://localhost:6767/v1/sessions/conv_abc123/resources/files" \
  -H "Authorization: Bearer <token>" \
  -F "file=@./data.csv"

Response — 201 Created:

{
  "id": "file_abc123",
  "object": "session.resource",
  "type": "file",
  "session_id": "conv_abc123",
  "name": "data.csv",
  "metadata": {
    "filename": "data.csv",
    "bytes": 4096,
    "content_type": "text/csv"
  }
}

Get File Metadata

GET /v1/sessions/{session_id}/resources/files/{file_id} Returns metadata for a session file resource. Verifies that file_id belongs to session_id.

Download File Content

GET /v1/sessions/{session_id}/resources/files/{file_id}/content Downloads the raw bytes of a session file. Response includes Content-Type set to the file’s media type.

Delete a File

DELETE /v1/sessions/{session_id}/resources/files/{file_id} Deletes a session file resource and its stored bytes.

Terminal Resources

Terminal resources are interactive shell sessions running on the host inside the session’s environment.

List Session Terminals

GET /v1/sessions/{session_id}/resources/terminals Returns terminal resources for the session. Pagination parameters (limit, after, before, order) are forwarded to the runner.

Launch a Terminal

POST /v1/sessions/{session_id}/resources/terminals Launches a terminal or returns an existing one (idempotent on terminal + session_key). User-initiated creates are gated on the agent spec’s terminals: block — the requested terminal name must be declared in the agent spec.

curl -X POST \
  "http://localhost:6767/v1/sessions/conv_abc123/resources/terminals" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"terminal": "shell", "session_key": "main"}'

Response:

{
  "id": "terminal_bash_s1",
  "object": "session.resource",
  "type": "terminal",
  "session_id": "conv_abc123",
  "name": "shell",
  "environment": "default"
}

Get a Terminal

GET /v1/sessions/{session_id}/resources/terminals/{terminal_id} Returns a single terminal resource object.

Close a Terminal

DELETE /v1/sessions/{session_id}/resources/terminals/{terminal_id} Closes the terminal. Returns 404 for unknown terminals.

Transfer a Terminal

POST /v1/sessions/{session_id}/resources/terminals/{terminal_id}/transfer Moves a terminal resource to another session without closing it. Used by native Claude /clear rotation where the tmux pane keeps running but ownership transfers to the new conversation.

{ "target_session_id": "conv_new456" }

Environment Resources

Environments are sandboxed workspaces with a filesystem, file watching, search, diff support, and shell execution.

List Environments

GET /v1/sessions/{session_id}/resources/environments Returns environment resources for the session.

Get an Environment

GET /v1/sessions/{session_id}/resources/environments/{environment_id} Returns a single environment resource. The environment_id for the default workspace is typically "default".

Browse Filesystem (Root)

GET /v1/sessions/{session_id}/resources/environments/{environment_id}/filesystem Lists the root directory of the environment.

limit

integer

default:"20"

Maximum entries to return.

after

string

Forward pagination cursor.

order

string

default:"desc"

Sort direction.

Browse Filesystem (Path)

GET /v1/sessions/{session_id}/resources/environments/{environment_id}/filesystem/{relative_path} Reads a file or lists a directory at relative_path (relative to the environment root). Returns file content or a paginated directory listing.

Write a File

PUT /v1/sessions/{session_id}/resources/environments/{environment_id}/filesystem/{relative_path} Writes or replaces a file at the given path.

{ "content": "print('hello world')\n" }

Edit a File (Text Replacement)

PATCH /v1/sessions/{session_id}/resources/environments/{environment_id}/filesystem/{relative_path} Edits a file via text replacement.

{ "old_text": "hello world", "new_text": "goodbye world" }

Delete a Path

DELETE /v1/sessions/{session_id}/resources/environments/{environment_id}/filesystem/{relative_path} Deletes a file or directory at the given path.

List Changed Files

GET /v1/sessions/{session_id}/resources/environments/{environment_id}/changes Returns a flat list of all files changed since the session started (created, modified, or deleted). Backed by the runner’s filesystem watchdog. Response:

{
  "data": [
    { "path": "src/main.py", "status": "modified" },
    { "path": "tests/test_auth.py", "status": "created" }
  ]
}

Diff a File

GET /v1/sessions/{session_id}/resources/environments/{environment_id}/diff/{relative_path} Returns before/after content for a changed file. Returns 404 when the file has not been modified this session. Response:

{
  "before": "# original content\n",
  "after": "# modified content\n"
}

Search Files

GET /v1/sessions/{session_id}/resources/environments/{environment_id}/search Searches for files by name/path substring. Returns matching file entries (not directories).

string

required

Case-insensitive search substring. Must contain at least one non-whitespace character.

include

string

Comma-separated glob patterns to scope results, e.g. "*.ts,src/**".

exclude

string

Comma-separated glob patterns to exclude, e.g. "**/node_modules,*.test.ts".

limit

integer

default:"500"

Maximum results. Range: 1–500.

Run Shell Command

POST /v1/sessions/{session_id}/resources/environments/{environment_id}/shell Executes a shell command in the environment.

{
  "command": "npm test",
  "timeout": 30
}

Response:

{
  "exit_code": 0,
  "stdout": "...",
  "stderr": ""
}

Overview

Sessions

Hosts & Runners

Resources

Session Resources API: Files, Terminals, and Environments

Generic Resource Endpoints

List All Resources

Get a Resource by ID

File Resources

List Session Files

Upload a File

Get File Metadata

Download File Content

Delete a File

Terminal Resources

List Session Terminals

Launch a Terminal

Get a Terminal

Close a Terminal

Transfer a Terminal

Environment Resources

List Environments

Get an Environment

Browse Filesystem (Root)

Browse Filesystem (Path)

Write a File

Edit a File (Text Replacement)

Delete a Path

List Changed Files

Diff a File

Search Files

Run Shell Command

Build docs developers (and LLMs) love

Overview

Sessions

Hosts & Runners

Resources

Documentation Index

​Generic Resource Endpoints

​List All Resources

​Get a Resource by ID

​File Resources

​List Session Files

​Upload a File

​Get File Metadata

​Download File Content

​Delete a File

​Terminal Resources

​List Session Terminals

​Launch a Terminal

​Get a Terminal

​Close a Terminal

​Transfer a Terminal

​Environment Resources

​List Environments

​Get an Environment

​Browse Filesystem (Root)

​Browse Filesystem (Path)

​Write a File

​Edit a File (Text Replacement)

​Delete a Path

​List Changed Files

​Diff a File

​Search Files

​Run Shell Command

Build docs developers (and LLMs) love

Generic Resource Endpoints

List All Resources

Get a Resource by ID

File Resources

List Session Files

Upload a File

Get File Metadata

Download File Content

Delete a File

Terminal Resources

List Session Terminals

Launch a Terminal

Get a Terminal

Close a Terminal

Transfer a Terminal

Environment Resources

List Environments

Get an Environment

Browse Filesystem (Root)

Browse Filesystem (Path)

Write a File

Edit a File (Text Replacement)

Delete a Path

List Changed Files

Diff a File

Search Files

Run Shell Command