API docs by Redocly

Trellis API (1.0.0)

Download OpenAPI specification:

URL: https://trellis.dev License: Apache 2.0

Trellis is a development environment control plane that unifies local development, parallel branches, remote terminals, and live production logs.

Versioning

The API uses URL path versioning (/api/v1/...) for major versions. Within a major version, Stripe-style date-based versioning is supported via the Trellis-Version HTTP header (e.g., Trellis-Version: 2026-01-17).

By default, the latest behavior is used. Pin to a specific date version for stability when breaking changes are introduced within a major version. The version date represents when a particular API behavior was current.

Go Client Library

An official Go client library is available at github.com/wingedpig/trellis/pkg/client. It provides typed access to all endpoints and supports API versioning. See the documentation for usage examples.

Services

Service lifecycle management

List all services

header Parameters
Trellis-Version
string^\d{4}-\d{2}-\d{2}$
Example: 2026-01-17

API version date (e.g., 2026-01-17). This header can be sent with any API request. When omitted, the latest API behavior is used. Pin to a specific date for stability across API updates. The Go client library sets this automatically via WithVersion().

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get service details

path Parameters
name
required
string

Service name

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Start a service

path Parameters
name
required
string

Service name

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Stop a service

path Parameters
name
required
string

Service name

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Restart a service

path Parameters
name
required
string

Service name

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get service logs

path Parameters
name
required
string

Service name

query Parameters
lines
integer
Default: 100

Number of log lines to return

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Clear service logs

path Parameters
name
required
string

Service name

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Stream service logs (SSE)

path Parameters
name
required
string

Service name

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Worktrees

Git worktree management

List all worktrees

header Parameters
Trellis-Version
string^\d{4}-\d{2}-\d{2}$
Example: 2026-01-17

API version date (e.g., 2026-01-17). This header can be sent with any API request. When omitted, the latest API behavior is used. Pin to a specific date for stability across API updates. The Go client library sets this automatically via WithVersion().

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Create a new worktree

Request Body schema: application/json
required
branch_name
required
string

Branch name to create worktree from

switch_to
boolean
Default: false

Whether to activate the new worktree

Responses

Request samples

Content type
application/json
{
  • "branch_name": "string",
  • "switch_to": false
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get worktrees info with project metadata

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get worktree details

path Parameters
name
required
string

Worktree name

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Remove a worktree

path Parameters
name
required
string

Worktree name

query Parameters
delete_branch
boolean
Default: false

Whether to delete the associated branch

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Activate a worktree

path Parameters
name
required
string

Worktree name

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Workflows

Workflow execution

List all workflows

header Parameters
Trellis-Version
string^\d{4}-\d{2}-\d{2}$
Example: 2026-01-17

API version date (e.g., 2026-01-17). This header can be sent with any API request. When omitted, the latest API behavior is used. Pin to a specific date for stability across API updates. The Go client library sets this automatically via WithVersion().

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get workflow details

path Parameters
id
required
string

Workflow ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Run a workflow

path Parameters
id
required
string

Workflow ID

query Parameters
worktree
string

Worktree to run workflow in

Request Body schema: application/json

Workflow inputs

object

Input values keyed by input name

Responses

Request samples

Content type
application/json
{
  • "inputs": { }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get workflow status

path Parameters
id
required
string

Workflow ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Stream workflow output (WebSocket)

path Parameters
runId
required
string

Workflow run ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Events

Event history and real-time subscriptions

Get event history

query Parameters
type
Array of strings

Event types to filter (supports wildcards)

worktree
string

Filter by worktree name

limit
integer

Maximum events to return

since
string <date-time>

Events after this time

until
string <date-time>

Events before this time

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Subscribe to events (WebSocket)

query Parameters
pattern
string
Default: "*"

Event pattern to subscribe to

Responses

Logs

Log viewer management

List log viewers

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get log viewer status

path Parameters
name
required
string

Log viewer name

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get log entries

path Parameters
name
required
string

Log viewer name

query Parameters
filter
string

Filter expression

limit
integer
Default: 1000

Maximum entries to return

before
string <date-time>

Only entries before this time

after
string <date-time>

Only entries after this time

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get historical log entries

path Parameters
name
required
string

Log viewer name

query Parameters
start
required
string <date-time>

Start of time range

end
required
string <date-time>

End of time range

filter
string

Filter expression

limit
integer
Default: 10000

Maximum entries

grep
string

Grep pattern for matching

before
integer

Context lines before match

after
integer

Context lines after match

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

List rotated log files

path Parameters
name
required
string

Log viewer name

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Stream log entries (WebSocket)

path Parameters
name
required
string

Log viewer name

query Parameters
filter
string

Initial filter expression

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Stream log entries (SSE)

path Parameters
name
required
string

Log viewer name

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Trace

Distributed tracing

Execute a distributed trace search

Request Body schema: application/json
required
id
required
string

Trace ID to search for

group
required
string

Trace group name

start
required
string <date-time>

Start of time range

end
string <date-time>

End of time range (default now)

name
string

Report name (auto-generated if empty)

expand_by_id
boolean
Default: true

Whether to expand by ID

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "group": "string",
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "expand_by_id": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

List trace groups

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

List trace reports

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get trace report

path Parameters
name
required
string

Report name

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Delete trace report

path Parameters
name
required
string

Report name

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Crashes

Crash report management

List all crashes

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Clear all crashes

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get most recent crash

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get crash by ID

path Parameters
id
required
string

Crash ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete crash

path Parameters
id
required
string

Crash ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Terminal

Terminal session management

List terminal sessions

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Terminal WebSocket connection

query Parameters
session
required
string

Session name

window
required
string

Window name

remote
integer
Enum: 0 1

Whether this is a remote connection

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Create a terminal window

path Parameters
worktree
required
string

Worktree name

Request Body schema: application/json
name
string

Window name (auto-generated if omitted)

command
string

Command to execute in the window

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "command": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "session": "string"
}

Rename a terminal window

path Parameters
worktree
required
string

Worktree name

window
required
string

Window name

Request Body schema: application/json
required
name
required
string

New window name

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Delete a terminal window

path Parameters
worktree
required
string

Worktree name

window
required
string

Window name

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Navigation

UI navigation options

Get navigation options

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Notify

Notification events

Emit a notification event

Request Body schema: application/json
required
message
required
string

Notification message

type
string
Default: "done"
Enum: "done" "blocked" "error"

Notification type

Responses

Request samples

Content type
application/json
{
  • "message": "string",
  • "type": "done"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Cases

Case management for tracking units of work

List open cases

path Parameters
worktree
required
string

Worktree name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a case

path Parameters
worktree
required
string

Worktree name

Request Body schema: application/json
required
title
required
string

Case title

kind
string
Default: "task"
Enum: "task" "bug" "feature" "investigation"

Case kind

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "kind": "task"
}

Response samples

Content type
application/json
{
  • "schema": "trellis.case.v1",
  • "id": "string",
  • "title": "string",
  • "kind": "task",
  • "status": "open",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "worktree": {
    },
  • "links": [
    ],
  • "evidence": [
    ],
  • "claude": [
    ],
  • "codex": [
    ],
  • "commits": [
    ],
  • "summary": {
    }
}

List archived cases

path Parameters
worktree
required
string

Worktree name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get case details

path Parameters
worktree
required
string

Worktree name

id
required
string

Case ID (e.g., 2026-02-19__fix-login-crash)

Responses

Response samples

Content type
application/json
{
  • "schema": "trellis.case.v1",
  • "id": "string",
  • "title": "string",
  • "kind": "task",
  • "status": "open",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "worktree": {
    },
  • "links": [
    ],
  • "evidence": [
    ],
  • "claude": [
    ],
  • "codex": [
    ],
  • "commits": [
    ],
  • "summary": {
    }
}

Update a case

path Parameters
worktree
required
string

Worktree name

id
required
string

Case ID (e.g., 2026-02-19__fix-login-crash)

Request Body schema: application/json
required
title
string
kind
string
Enum: "task" "bug" "feature" "investigation"
status
string
Enum: "open" "resolved" "wontfix"
Array of objects (CaseLink)

Full array replaces existing links

notes
string

Overwrites notes.md content

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "kind": "task",
  • "status": "open",
  • "links": [
    ],
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Delete a case

path Parameters
worktree
required
string

Worktree name

id
required
string

Case ID (e.g., 2026-02-19__fix-login-crash)

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Get case notes

path Parameters
worktree
required
string

Worktree name

id
required
string

Case ID (e.g., 2026-02-19__fix-login-crash)

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Archive a case

path Parameters
worktree
required
string

Worktree name

id
required
string

Case ID (e.g., 2026-02-19__fix-login-crash)

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Reopen an archived case

path Parameters
worktree
required
string

Worktree name

id
required
string

Case ID (e.g., 2026-02-19__fix-login-crash)

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Attach evidence file to a case

path Parameters
worktree
required
string

Worktree name

id
required
string

Case ID (e.g., 2026-02-19__fix-login-crash)

Request Body schema: multipart/form-data
required
file
required
string <binary>

Evidence file to attach

title
string

Title (defaults to filename)

tags
Array of strings

Tags for the evidence

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "filename": "string",
  • "format": "string",
  • "tags": [
    ],
  • "added_at": "2019-08-24T14:15:22Z"
}

Save a Claude transcript to a case

path Parameters
worktree
required
string

Worktree name

id
required
string

Case ID (e.g., 2026-02-19__fix-login-crash)

Request Body schema: application/json
required
session_id
required
string

Claude session UUID

title
string

Transcript title (defaults to session display name)

Responses

Request samples

Content type
application/json
{
  • "session_id": "string",
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "claude_ref_id": "string",
  • "title": "string"
}

Update a transcript with latest messages from its live session

path Parameters
worktree
required
string

Worktree name

id
required
string

Case ID (e.g., 2026-02-19__fix-login-crash)

claude_id
required
string

Claude transcript reference ID

Responses

Response samples

Content type
application/json
{
  • "claude_ref_id": "string",
  • "message_count": 0
}

Continue a transcript in a new Claude session

path Parameters
worktree
required
string

Worktree name

id
required
string

Case ID (e.g., 2026-02-19__fix-login-crash)

claude_id
required
string

Claude transcript reference ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "worktree_name": "string",
  • "display_name": "string",
  • "last_user_input": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "trashed_at": "2019-08-24T14:15:22Z"
}

Save a trace report to a case

path Parameters
worktree
required
string

Worktree name

id
required
string

Case ID (e.g., 2026-02-19__fix-login-crash)

Request Body schema: application/json
required
report_name
required
string

Name of trace report to save

Responses

Request samples

Content type
application/json
{
  • "report_name": "string"
}

Response samples

Content type
application/json
{
  • "trace_ref_id": "string",
  • "report_name": "string"
}

Delete a saved trace from a case

path Parameters
worktree
required
string

Worktree name

id
required
string

Case ID (e.g., 2026-02-19__fix-login-crash)

trace_id
required
string

Trace reference ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Full-text search over archived cases

Scans case.json files (title, summary fields, commit descriptions) and notes.md for archived cases in the worktree, applying optional filters and ranking. Keyword and component matches rank above title matches, which rank above notes / commit-description matches.

path Parameters
worktree
required
string

Worktree name

query Parameters
q
string

Free-text query

kind
string
Enum: "task" "bug" "feature" "investigation"
from
string

Inclusive lower bound on created_at — accepts YYYY-MM-DD or RFC 3339

to
string

Inclusive upper bound on created_at — accepts YYYY-MM-DD or RFC 3339

has_traces
string

Set to "1" to require at least one linked trace

include_transcripts
string

Set to "1" to also scan transcript previews (slower path)

sort
string
Default: "date"
Enum: "date" "kind" "duration" "worktree"

Sort key (results are always grouped by score first)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Apply partial edits to the generated case summary

path Parameters
worktree
required
string

Worktree name

id
required
string

Case ID (e.g., 2026-02-19__fix-login-crash)

Request Body schema: application/json
required
synopsis
string
symptoms
string
root_cause
string
resolution
string
components
Array of strings
keywords
Array of strings

Responses

Request samples

Content type
application/json
{
  • "synopsis": "string",
  • "symptoms": "string",
  • "root_cause": "string",
  • "resolution": "string",
  • "components": [
    ],
  • "keywords": [
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Re-run the case summary generator and overwrite the stored summary

Calls claude -p with the case's accumulated state (notes, commit descriptions, attached transcripts, linked traces) and replaces the stored summary. The client is expected to confirm before calling this if hand-edits may exist.

path Parameters
worktree
required
string

Worktree name

id
required
string

Case ID (e.g., 2026-02-19__fix-login-crash)

Responses

Response samples

Content type
application/json
{
  • "synopsis": "string",
  • "symptoms": "string",
  • "root_cause": "string",
  • "resolution": "string",
  • "components": [
    ],
  • "keywords": [
    ],
  • "generated_at": "2019-08-24T14:15:22Z",
  • "model": "string"
}

Claude

Claude Code session management, commits, and wrap-up

List Claude sessions for a worktree

path Parameters
worktree
required
string

Worktree name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new Claude session

path Parameters
worktree
required
string

Worktree name

Request Body schema: application/json
display_name
string

Session display name (auto-generated if omitted)

Responses

Request samples

Content type
application/json
{
  • "display_name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "worktree_name": "string",
  • "display_name": "string",
  • "last_user_input": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "trashed_at": "2019-08-24T14:15:22Z"
}

Import a transcript into a new session

path Parameters
worktree
required
string

Worktree name

Request Body schema: application/json
required
schema
string
exported_at
string <date-time>
object
Array of objects (ClaudeMessage)
object

Responses

Request samples

Content type
application/json
{
  • "schema": "string",
  • "exported_at": "2019-08-24T14:15:22Z",
  • "source": {
    },
  • "messages": [
    ],
  • "stats": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "worktree_name": "string",
  • "display_name": "string",
  • "last_user_input": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "trashed_at": "2019-08-24T14:15:22Z"
}

List trashed sessions for a worktree

path Parameters
worktree
required
string

Worktree name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Rename a Claude session

path Parameters
session
required
string

Claude session UUID

Request Body schema: application/json
required
display_name
required
string

New display name

Responses

Request samples

Content type
application/json
{
  • "display_name": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Trash a Claude session

path Parameters
session
required
string

Claude session UUID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Claude session WebSocket connection

path Parameters
session
required
string

Claude session UUID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Export a Claude session transcript

path Parameters
session
required
string

Claude session UUID

query Parameters
level
string
Default: "full"
Enum: "full" "summary"

Export detail level

Responses

Response samples

Content type
application/json
{
  • "schema": "string",
  • "exported_at": "2019-08-24T14:15:22Z",
  • "source": {
    },
  • "messages": [
    ],
  • "stats": {
    }
}

Restore a trashed session

path Parameters
session
required
string

Claude session UUID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Permanently delete a trashed session

path Parameters
session
required
string

Claude session UUID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Fork a session at a message index

Creates a new Claude session in the same worktree as the source, pre-populated with the source session's messages[0..message_index] (inclusive). The source session is untouched. The Claude CLI's JSONL session file is rewritten for the new session so --resume continues from exactly that point.

path Parameters
session
required
string

Claude session UUID

Request Body schema: application/json
required
message_index
required
integer >= 0

0-based inclusive index of the last message to include in the fork

display_name
required
string

Display name for the new session

Responses

Request samples

Content type
application/json
{
  • "message_index": 0,
  • "display_name": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Move a session to a fresh worktree

Creates a new git worktree on the given branch, copies the selected uncommitted files from the source worktree into it, reverts those files in the source (via git checkout -- for tracked files or delete for untracked files), and rebinds the Claude session to the new worktree. The running Claude process is stopped; it will restart in the new working directory on the next message.

path Parameters
session
required
string

Claude session UUID

Request Body schema: application/json
required
branch
required
string

Branch name for the new worktree (must not already exist)

files
Array of strings

Relative paths (from the source worktree root) of files to move. May include modified, added, or untracked files. Directories and symlinks are not supported.

Responses

Request samples

Content type
application/json
{
  • "branch": "string",
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Claude WebSocket by worktree (backwards compatibility)

path Parameters
worktree
required
string

Worktree name

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Get git status for a worktree

path Parameters
worktree
required
string

Worktree name

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Check if a session is linked to an open case

path Parameters
worktree
required
string

Worktree name

query Parameters
session_id
required
string

Claude session ID to look up

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Wrap up a session — generate summary, archive case, commit

Wrap Up is the shared commitToCase orchestrator with archive: true. It generates a case summary via claude -p, archives the case directory from cases/ to cases-archived/, includes the archived directory in the git commit, and trashes the active session.

path Parameters
worktree
required
string

Worktree name

Request Body schema: application/json
required
session_id
string

Active Claude/Codex session ID. Used to attach the session transcript when a case is being created.

case_id
string

Explicit case ID. Omit to bind to the worktree's open case (or create one if none exists).

title
string

New-case title — required only when no open case exists and no case_id is supplied.

kind
string
Enum: "task" "bug" "feature" "investigation"

New-case kind. Defaults to feature on the commit path.

commit_message
required
string
description
string

Per-commit case description (intermediate commits only — recorded on the CommitEntry).

files
Array of strings

Files to git add. Paths under the live cases directory are rejected.

Array of objects (CaseLink)

(Wrap-up only) Links to merge into the case.

traces
Array of strings

(Wrap-up only) Trace report names to save into the case.

Array of objects

(Wrap-up only) Other-agent sessions to capture into the case and trash.

object

(Wrap-up only) User-curated summary from the modal. When non-nil and synopsis is non-empty, the server uses this summary verbatim (with light normalization on components/keywords) and skips the in-line claude -p summary generation. The expected flow: the client GET .../generate-summary, the user prunes the chips, then ships the edited result back here.

Responses

Request samples

Content type
application/json
{
  • "session_id": "string",
  • "case_id": "string",
  • "title": "string",
  • "kind": "task",
  • "commit_message": "string",
  • "description": "string",
  • "files": [
    ],
  • "links": [
    ],
  • "traces": [
    ],
  • "related_sessions": [
    ],
  • "summary": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Make an intermediate commit against the worktree's open case

Same orchestrator as wrap-up but archive: false. Creates the case on first commit if none exists; binds to the worktree's single open case otherwise. Appends a CommitEntry to case.json and leaves the case open and the session alive.

path Parameters
worktree
required
string

Worktree name

Request Body schema: application/json
required
session_id
string

Active Claude/Codex session ID. Used to attach the session transcript when a case is being created.

case_id
string

Explicit case ID. Omit to bind to the worktree's open case (or create one if none exists).

title
string

New-case title — required only when no open case exists and no case_id is supplied.

kind
string
Enum: "task" "bug" "feature" "investigation"

New-case kind. Defaults to feature on the commit path.

commit_message
required
string
description
string

Per-commit case description (intermediate commits only — recorded on the CommitEntry).

files
Array of strings

Files to git add. Paths under the live cases directory are rejected.

Array of objects (CaseLink)

(Wrap-up only) Links to merge into the case.

traces
Array of strings

(Wrap-up only) Trace report names to save into the case.

Array of objects

(Wrap-up only) Other-agent sessions to capture into the case and trash.

object

(Wrap-up only) User-curated summary from the modal. When non-nil and synopsis is non-empty, the server uses this summary verbatim (with light normalization on components/keywords) and skips the in-line claude -p summary generation. The expected flow: the client GET .../generate-summary, the user prunes the chips, then ships the edited result back here.

Responses

Request samples

Content type
application/json
{
  • "session_id": "string",
  • "case_id": "string",
  • "title": "string",
  • "kind": "task",
  • "commit_message": "string",
  • "description": "string",
  • "files": [
    ],
  • "links": [
    ],
  • "traces": [
    ],
  • "related_sessions": [
    ],
  • "summary": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Draft a commit message and per-commit description via `claude -p`

Shells out to claude -p --output-format json with a diff covering exactly the files the caller passes in files (NOT git diff --staged — the staging area may hold unrelated work; HEAD-vs-WT includes files the user unchecked). Inputs also include the case manifest, notes, and a few recent user messages from the session. Returns a freeform commit message and a 1-2 sentence per-commit description (the "narrative beat"). No Anthropic API key is required — uses the user's existing Claude Code authentication.

path Parameters
worktree
required
string

Worktree name

Request Body schema: application/json
required
files
required
Array of strings

Files the user has selected for this commit. The generated message describes the diff of exactly these files.

session_id
string
case_id
string
title
string

New-case title — used when no case yet exists

kind
string
Enum: "task" "bug" "feature" "investigation"

Responses

Request samples

Content type
application/json
{
  • "files": [
    ],
  • "session_id": "string",
  • "case_id": "string",
  • "title": "string",
  • "kind": "task"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Preview the case summary the wrap-up would generate

Runs the case summary generator (claude -p) against the supplied case context without committing. Used by the wrap-up modal so the user can review and prune the generated components and keywords before confirming. The client is expected to send the (possibly edited) summary back as summary on the wrap-up request.

path Parameters
worktree
required
string

Worktree name

Request Body schema: application/json
optional
case_id
string

Case to summarize. If omitted, the worktree's open case is used.

files
Array of strings

Files selected for the wrap-up commit — scopes the diff input.

Responses

Request samples

Content type
application/json
{
  • "case_id": "string",
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "synopsis": "string",
  • "symptoms": "string",
  • "root_cause": "string",
  • "resolution": "string",
  • "components": [
    ],
  • "keywords": [
    ],
  • "generated_at": "2019-08-24T14:15:22Z",
  • "model": "string"
}

Codex

OpenAI Codex session management, commits, and wrap-up

Wrap up a Codex session — generate summary, archive case, commit

path Parameters
worktree
required
string

Worktree name

Request Body schema: application/json
required
session_id
string

Active Claude/Codex session ID. Used to attach the session transcript when a case is being created.

case_id
string

Explicit case ID. Omit to bind to the worktree's open case (or create one if none exists).

title
string

New-case title — required only when no open case exists and no case_id is supplied.

kind
string
Enum: "task" "bug" "feature" "investigation"

New-case kind. Defaults to feature on the commit path.

commit_message
required
string
description
string

Per-commit case description (intermediate commits only — recorded on the CommitEntry).

files
Array of strings

Files to git add. Paths under the live cases directory are rejected.

Array of objects (CaseLink)

(Wrap-up only) Links to merge into the case.

traces
Array of strings

(Wrap-up only) Trace report names to save into the case.

Array of objects

(Wrap-up only) Other-agent sessions to capture into the case and trash.

object

(Wrap-up only) User-curated summary from the modal. When non-nil and synopsis is non-empty, the server uses this summary verbatim (with light normalization on components/keywords) and skips the in-line claude -p summary generation. The expected flow: the client GET .../generate-summary, the user prunes the chips, then ships the edited result back here.

Responses

Request samples

Content type
application/json
{
  • "session_id": "string",
  • "case_id": "string",
  • "title": "string",
  • "kind": "task",
  • "commit_message": "string",
  • "description": "string",
  • "files": [
    ],
  • "links": [
    ],
  • "traces": [
    ],
  • "related_sessions": [
    ],
  • "summary": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Make an intermediate commit against the worktree's open case (Codex)

path Parameters
worktree
required
string

Worktree name

Request Body schema: application/json
required
session_id
string

Active Claude/Codex session ID. Used to attach the session transcript when a case is being created.

case_id
string

Explicit case ID. Omit to bind to the worktree's open case (or create one if none exists).

title
string

New-case title — required only when no open case exists and no case_id is supplied.

kind
string
Enum: "task" "bug" "feature" "investigation"

New-case kind. Defaults to feature on the commit path.

commit_message
required
string
description
string

Per-commit case description (intermediate commits only — recorded on the CommitEntry).

files
Array of strings

Files to git add. Paths under the live cases directory are rejected.

Array of objects (CaseLink)

(Wrap-up only) Links to merge into the case.

traces
Array of strings

(Wrap-up only) Trace report names to save into the case.

Array of objects

(Wrap-up only) Other-agent sessions to capture into the case and trash.

object

(Wrap-up only) User-curated summary from the modal. When non-nil and synopsis is non-empty, the server uses this summary verbatim (with light normalization on components/keywords) and skips the in-line claude -p summary generation. The expected flow: the client GET .../generate-summary, the user prunes the chips, then ships the edited result back here.

Responses

Request samples

Content type
application/json
{
  • "session_id": "string",
  • "case_id": "string",
  • "title": "string",
  • "kind": "task",
  • "commit_message": "string",
  • "description": "string",
  • "files": [
    ],
  • "links": [
    ],
  • "traces": [
    ],
  • "related_sessions": [
    ],
  • "summary": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Preview the case summary the wrap-up would generate (Codex)

path Parameters
worktree
required
string

Worktree name

Request Body schema: application/json
optional
case_id
string
files
Array of strings

Responses

Request samples

Content type
application/json
{
  • "case_id": "string",
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "synopsis": "string",
  • "symptoms": "string",
  • "root_cause": "string",
  • "resolution": "string",
  • "components": [
    ],
  • "keywords": [
    ],
  • "generated_at": "2019-08-24T14:15:22Z",
  • "model": "string"
}

Draft a commit message and per-commit description for a Codex session

path Parameters
worktree
required
string

Worktree name

Request Body schema: application/json
required
files
required
Array of strings

Files the user has selected for this commit.

session_id
string
case_id
string
title
string
kind
string
Enum: "task" "bug" "feature" "investigation"

Responses

Request samples

Content type
application/json
{
  • "files": [
    ],
  • "session_id": "string",
  • "case_id": "string",
  • "title": "string",
  • "kind": "task"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Inbox

Aggregated cross-agent session inbox (for the floating popup window)

Initial merged list of active sessions for the inbox popup

Returns every active Claude and Codex session across all worktrees, with a coarse running / needs_you state and the timestamp of the last state transition. The inbox popup uses this for its initial render; thereafter it relies on the session.state_changed events delivered over the inbox WebSocket.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

WebSocket — multiplexed inbox endpoint (role=inbox or role=main)

Single WebSocket endpoint that serves two roles via the role query parameter:

  • role=inbox — opened by the floating inbox popup. Receives state_changed events; can send {type:"navigate", path:"..."} commands which the server forwards to every connected role=main. If no main window is connected, the server replies to the popup with navigate_failed.

  • role=main — opened by every regular Trellis page via inbox_main_ws.js. Receives {type:"navigate", path:"..."} commands and acts on them by setting window.location.href. Reads are drained for close detection only; clients never send application messages.

query Parameters
role
required
string
Enum: "inbox" "main"

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

VSCode

VS Code integration

Open file in VS Code

Request Body schema: application/json
required
path
required
string

File path to open

line
integer

Line number

column
integer

Column number

Responses

Request samples

Content type
application/json
{
  • "path": "string",
  • "line": 0,
  • "column": 0
}