API / SDK / CLI reference

Base URL https://api.opencomputer.dev/v3. Management calls authenticate with your org API key; stream and steer also accept a client token. Each section toggles between the TypeScript SDK (@opencomputer/sdk), REST, and the oc CLI — pick one and the whole page follows.

import { OpenComputer, connectSession } from "@opencomputer/sdk";

const oc = new OpenComputer({ apiKey: process.env.OPENCOMPUTER_API_KEY! });
const session = await oc.sessions.get("ses_...");        // server, org key
// or, in a browser:  await connectSession({ sessionId, clientToken })

# the oc CLI authenticates with OPENCOMPUTER_API_KEY (or `oc login`); --json on any command
oc whoami
oc agent deploy        # deploy the agent directory in the cwd
oc agent build --dir . --check-only --json  # validate a Flue app without credentials or deployment

The SDK uses camelCase for fields and params (last_turn → lastTurn, idempotency_key → idempotencyKey); the wire shapes below are raw JSON. Opaque blobs — session metadata, event refs/raw — pass through verbatim; everything else (incl. event body) is camelCased. The CLI prints a table, or raw JSON with --json.

Sessions

TypeScript SDK
REST API
oc CLI

Call	Purpose
`oc.sessions.create(params)`	Start a session → a `Session` handle (carries `.clientToken`).
`oc.sessions.get(id)`	Fetch a session.
`oc.sessions.list(params)`	List sessions (filtered, paginated).
`session.archive()`	Cancel any active turn, then close (read-only).
`session.cancel()`	Cooperatively stop the active turn (no-op if not running).
`session.result()`	`{ lastTurn, result? }` — the resolved final event.
`session.turns()` · `session.turn(id)`	Per-turn history: timing, error.
`session.sources` · `session.listSources()`	Source checkout status — create snapshot · live poll.
`session.mintClientToken(opts)`	Mint a client token.

Method · Path	Purpose
`POST /sessions`	Start a session → `{ session, client_token }`.
`GET /sessions/:id`	Fetch a session.
`GET /sessions?status=&agent=&key=&after=&before=&limit=&cursor=`	List sessions (filtered, paginated; `cursor` = `nextCursor`).
`POST /sessions/:id/archive`	Cancel any active turn, then close (read-only).
`POST /sessions/:id/cancel`	Cooperatively stop the active turn (no-op if not running).
`GET /sessions/:id/result`	The result helper — `{ last_turn, result? }`.
`GET /sessions/:id/turns` · `…/turns/:turnId`	Per-turn history: timing, error.
`GET /sessions/:id/sources`	Source checkout status (`SourceSummary[]`).
`POST /sessions/:id/client-tokens`	Mint a client token.

Command	Purpose
`oc session create --agent <id\|name> [--revision <n>] [--input <text>]`	Start a session (`--revision` pins a specific revision; default = active).
`oc session get <id>`	Fetch a session.
`oc session list [--agent <id>] [--status <s>]`	List sessions.
`oc session cancel <id>`	Cooperatively stop the active turn.
`oc session result <id>`	The resolved final result.
`oc session steer <id> <text>`	Send input to a running or waiting session.
(archive · turns · sources · client tokens — REST/SDK only)

Create params — agent is required; the model resolves to Managed (default) or a credential, else 422 no_credential / 422 managed_unavailable.

input — the task (string or envelope). Truncate large inputs; let the agent fetch the rest via sandbox tools.
revision?: pin a specific revision (number / rev_…); default = the agent’s active one. Use to test a staged built-in runtime revision. A Flue agent has one live Worker, so an old revision does not isolate older Worker code.
model? — run this session on a different model than the agent’s (same provider/model form; its provider must match the agent’s runtime, e.g. anthropic/… for claude). Default = the agent’s model. Pinned for the session’s life like the rest of the snapshot. Rejected (400 invalid) for flue agents — their model is fixed in the deployed artifact.
key? — get-or-create (one session per key). Keyless: an Idempotency-Key header makes create retry-safe.
metadata? — opaque routing state (≤ 16 KB); on get/list + verbatim in webhooks; never sent to the model, not indexed.
limits? { tokens, turn_seconds, turns }: non-monetary; tripping one ends a built-in runtime turn with the matching yield_reason. These limits are stored but not yet enforced for Flue sessions.
sources?: repos checked out before turn 1 for built-in runtimes (the token never enters the sandbox; see GitHub). Each registered { repo, ref, sha?, name? } or inline { url, ref, sha, name?, auth }. ref is required; sha is required for inline sources but optional for a registered repo. Flue sessions reject sources with 422 sources_not_supported.
Client tokens: scopes? (read/steer), ttl? 60–86400 s (SDK ttlSeconds).

A built-in runtime session pins the agent’s active revision for its whole life. A Flue session records its selected deployment but executes on the agent’s one live Worker; deploying that Worker can therefore affect an existing session. Session

Field	Type	Notes
`id` `status` `head` `input_cursor`		id, lifecycle status, latest event seq, input cursor
`agent_id` `credential_id`	string	resolved + pinned at create
`agent_snapshot`	object	`{ prompt_hash, model, runtime, revision }` — `revision` = the pinned revision number
`last_turn`	`Turn`-ish	`{ id, state, yield_reason?, result_event_id? }`
`limits?`	object	`{ tokens?, turn_seconds?, turns? }`
`metadata?`	object	opaque app routing state
`key?` `created_at`		get-or-create key, timestamp

Turn

Field	Notes
`id` `state`	turn id, current state
`yield_reason?`	why it ended (below)
`result_event_id?`	the event carrying the result
`error?`	failure detail, if any
`started_at?` `completed_at?`	timing

A turn’s yield_reason tells you why it stopped:

Value	Meaning
`completed`	finished normally
`needs_input`	the agent asked a question — answer it by steering
`error`	the turn failed (see `error`)
`budget_exceeded` / `deadline_exceeded` / `max_turns`	a limit tripped — tokens / wall-clock / auto-runs
`canceled`	you cancelled it

SessionSource — one of two variants:

Variant	Shape
registered	`{ repo, ref, sha?, name? }` — `repo` is a `repo_…` id or `"owner/repo"`; App-backed auth. `sha` is optional (omit → control plane resolves `ref`→HEAD and pins it at create)
inline	`{ url, ref, sha, name?, auth }` — `sha` required; `auth = { type:"risky_short_lived_token", token, expires_at }` (can’t refresh)

SourceSummary (sanitized; on create + GET …/sources)

Field	Notes
`name` `path` `sha` `resolved_sha?`	checkout identity + resolved commit
`status`	`pending · materializing · resolved · failed · unavailable · auth_required`
`error_code?` `error_message?` `retryable?`	on failure — `source.`-prefixed, e.g. `source.auth_required` (App not installed), `source.repo_not_selected` (install doesn’t cover the repo), `source.permission_missing`, `source.mint_failed`, `source.ref_not_found`, `source.sha_mismatch`. Full list

Events

TypeScript SDK
REST API
oc CLI

Call	Purpose
`session.listEvents(opts)`	Read events since a cursor.
`session.events(opts)`	Live stream from a cursor — a self-resuming async iterator.
`session.event(id)`	Fetch one event (resolve `resultEventId`).
`session.eventContent(id)`	Fetch a blob-backed body (large outputs).
`session.messages(opts)`	User-message history.

Method · Path	Purpose
`GET /sessions/:id/events?after=<seq>&level=<lvl>`	Read events since a cursor.
`GET /sessions/:id/events?…&stream=sse`	Live SSE stream from a cursor.
`GET /sessions/:id/events/:eventId`	Fetch one event.
`GET /sessions/:id/events/:eventId/content`	Fetch a blob-backed body.
`GET /sessions/:id/messages`	User-message history.

Command	Purpose
`oc session logs <id> [--follow] [--level <lvl>] [--type <t>]`	Read or live-stream events.
(single event · event content · messages — REST/SDK only)

Filter by type (exact or prefix.*), turn_id, limit. after resumes from a seq; level is a visibility threshold — user < progress < internal (default internal; see visibility levels). Switch on type, don’t parse prose. …/messages is an alias for level=user + type=*.message. Event

Field	Notes
`id` `seq` `ts` `session`	id, monotonic seq, timestamp, session id
`actor` `type` `level`	source, event type, visibility level
`body`	the payload (camelCased; switch on `type`, don’t parse prose)
`turn_id?`	the turn it belongs to
`content_ref?` `body_truncated?` `body_bytes?`	large bodies are offloaded — fetch via `…/events/:id/content`

Steer

TypeScript SDK
REST API
oc CLI

Call	Purpose
`session.steer(text, { idempotencyKey })`	Append an input message; wakes the session.

Method · Path	Purpose
`POST /sessions/:id/messages`	Append an input message; wakes the session.

Command	Purpose
`oc session steer <id> <text>`	Append an input message; wakes the session.

Body: { text, idempotency_key? } or { envelope }. Returns 202 (or 200 on idempotent replay) with { event: { id, seq }, session: { id, status, head } }.

Watches

Managed with the SDK (session.watches.create/list/delete), the CLI (oc session watch/watches/unwatch), or REST — authenticate with your org API key (server-side). The agent-facing path is the watch_pull_request runtime tool. Full guide: Watches.

Method · Path	Purpose
`POST /sessions/:id/watches`	Declare a watch → `201 { watch }`. Body: `{ type:"github_pr", repo?, pr?, wake_on, intent? }`.
`GET /sessions/:id/watches`	List watches → `{ data: [watch] }`.
`DELETE /sessions/:id/watches/:watchId`	Remove a watch → `{ ok: true }`.

wake_on is the wake condition (checks default · review · comment · merge); intent is the freeform “why,” replayed on wake. repo/pr are optional — omitted, they resolve to the PR this session opened. A watch fires only on PRs the same session opened, on Connected-App (oc_app) repos. Limits: 10 active watches per session, 30-day TTL (and never outlives the PR). Watch

Field	Notes
`id` `type`	`wch_…`; `type` = `github_pr`
`repo` `pr`	watched repo · PR number
`wake_on`	wake condition: `checks` (default) · `review` (a review decision) · `comment` · `merge` (merged/closed)
`intent?`	freeform note (“why”), replayed on wake
`status`	`active · closed · revoked · auth_required`
`origin`	how it was declared (runtime tool / management API)
`last_snapshot_at?` `expires_at` `created_at`	last authoritative PR re-read · 30-day TTL lapse · timestamp

Delivered events — appended into the session log at level user with source: "github", carrying a normalized summary (not the raw webhook): github.pr.checks_completed · github.pr.review_submitted · github.pr.comment · github.pr.merged · github.pr.closed.

Agents

TypeScript SDK
REST API
oc CLI

Call	Purpose
`oc.agents.create(params)`	Create a reusable agent.
`oc.agents.repository.review(params)`	Resolve and interpret an exact repository source without running it.
`oc.agents.repository.import(params)`	Import an exact reviewed source and enqueue its first deployment.
`oc.agents.get(id)` · `oc.agents.list()`	Fetch / list.
`oc.agents.update(id, params)`	Update bindings (credential / limits) — `prompt`/`model` deploy a revision.
`oc.agents.delete(id)`	Delete an agent.

Method · Path	Purpose
`POST /agents`	Create a reusable agent.
`POST /agents/import`	Atomically create an agent from an exact reviewed GitHub source and enqueue its first deployment.
`GET /agents/:id` · `GET /agents`	Fetch / list.
`PATCH /agents/:id`	Update bindings; `prompt`/`model` deploy a revision.
`DELETE /agents/:id`	Delete an agent.

Command	Purpose
`oc agent create <name> --model <m> [--runtime claude\|codex]`	Create a reusable agent.
`oc agent get <id\|name>` · `oc agent list`	Fetch / list.
`oc agent update <id> [--credential <c>] [--limits …]`	Update bindings.
`oc agent delete <id>`	Delete an agent.

Body: name, prompt, model, runtime? (claude|codex), key?, credential?, limits?. PATCH takes the same minus runtime (fixed at create). runtime/model provider must agree (claude↔anthropic/…, codex↔openai/…). credential: a cred_… id (BYO, provider-matched) or "managed" (via OpenComputer, billed to credits) — mutually exclusive with key. POST /agents is idempotent by name: fresh → 201, matching config → 200, differing → 409. Editing prompt/model (here or via deploy) creates a revision; the agent keeps a pointer to its active revision (GET /agents/:id → active_revision) and sessions pin it. The agent row holds only identity + bindings. POST /agents/import is the reviewed repository-import command described below. It deliberately creates an agent with no active revision; revision #1 appears only after the queued build and live deployment verify successfully.

Deployments and revisions

You deploy an agent’s behavior. A deployment is a time-aware attempt; only a successful attempt produces an immutable revision. Failed attempts and their logs remain in deployment history. See the Deployments & revisions guide.

Review and import a repository agent

Review resolves the moving production branch to one exact commit and interprets bounded metadata without executing repository code. Repository-first import currently accepts the exact Flue result. GET /github/deploy-app returns the installed OpenComputer GitHub App and its pickable repositories. Each repository includes linked_sources[] with the owner-scoped path, production_ref, status, and owning agent { id, name }. Clients should block review when the selected normalized root has a claim. This is an early user-facing check; import repeats the uniqueness check transactionally.

const review = await oc.agents.repository.review({
  repo: "repo_...",
  path: "agents/support",
  productionRef: "main",
});

POST /github/deploy-app/inspect
Authorization: Bearer $OPENCOMPUTER_API_KEY

{
  "repo": "repo_...",
  "path": "agents/support",
  "production_ref": "main"
}

The response always includes repository identity, normalized root, production_ref, exact sha, review_fingerprint, and one interpretation:

Exact Flue review

{
  "repository": { "id": "repo_...", "full_name": "acme/agents", "default_branch": "main" },
  "root": "agents/support",
  "production_ref": "main",
  "sha": "0123456789abcdef0123456789abcdef01234567",
  "interpretation": {
    "disposition": "exact",
    "source_profile": "flue-app-v1",
    "source_profile_version": 1,
    "summary": "Flue agent detected",
    "reason_code": "flue_detected",
    "assumptions": [],
    "agent": { "runtime": "flue", "model": "anthropic/claude-haiku-4-5" }
  },
  "profile": {
    "source_profile": "flue-app-v1",
    "source_profile_version": 1,
    "manifest": { "schema_version": 1, "entrypoint": "support-triage", "model": "anthropic/claude-haiku-4-5", "runtime": { "family": "flue", "type": "default" }, "vars": {} },
    "package": { "name": "support-agent", "node_engine": ">=22.19 <23", "flue_cli": "1.0.0-beta.9" },
    "lockfile": { "version": 3 },
    "builder": { "node": "22.19.0" },
    "source": { "files": 12, "bytes": 4096 },
    "variable_names": [],
    "warnings": []
  },
  "review_fingerprint": "sha256:...",
  "candidate_roots": [],
  "candidate_roots_truncated": false
}

interpretation.disposition is exact, invalid, or unrecognized. Invalid and unrecognized are successful review responses, not service failures: invalid includes bounded issues; an unrecognized root can include up to 20 candidate_roots and explicitly reports truncation. Only exact includes a deployable profile and may proceed to import. No response contains a repository token or source bytes. The non-exact variants keep the common repository/root/SHA/fingerprint fields shown above and use these shapes:

Invalid or unrecognized interpretation

{
  "interpretation": {
    "disposition": "invalid",
    "source_profile": "flue-app-v1",
    "source_profile_version": 1,
    "summary": "This Flue agent needs a fix",
    "reason_code": "manifest_invalid",
    "issues": [
      { "code": "manifest_invalid", "message": "…", "path": "agent.toml" }
    ]
  },
  "profile": null,
  "candidate_roots": [],
  "candidate_roots_truncated": false
}

An unrecognized interpretation has source_profile: null, source_profile_version: null, and reason_code: "unrecognized_source". Its optional candidate entries are { path, source_profile: "flue-app-v1" | null, summary, marker }; selecting one always performs a new review. candidate_roots_truncated means more matches existed than the bounded response could return, so ask the user to choose a narrower root rather than selecting one automatically. Import sends the same source coordinates, a human-readable agent name, and the exact review receipt. The name is independent of the Flue entrypoint in agent.toml.

if (review.interpretation.disposition !== "exact") {
  throw new Error(review.interpretation.summary);
}

const result = await oc.agents.repository.import({
  name: "Support triage",
  credential: "managed",
  idempotencyKey: "stable-key-for-this-import",
  source: {
    type: "github",
    repo: review.repository.id,
    path: review.root,
    productionRef: review.productionRef,
  },
  review: {
    sha: review.sha,
    sourceProfile: review.interpretation.sourceProfile,
    fingerprint: review.reviewFingerprint,
  },
});

POST /agents/import
Authorization: Bearer $OPENCOMPUTER_API_KEY
Idempotency-Key: <stable-key-for-this-import>

{
  "name": "Support triage",
  "credential": "managed",
  "source": {
    "type": "github",
    "repo": "repo_...",
    "path": "agents/support",
    "production_ref": "main"
  },
  "review": {
    "sha": "0123456789abcdef0123456789abcdef01234567",
    "source_profile": "flue-app-v1",
    "fingerprint": "sha256:..."
  }
}

The server reauthorizes the repository and re-derives the reviewed plan, then creates { agent, source, deployment } atomically. If the branch head or relevant source changed, it returns 409 source_changed_re_review and creates nothing. Reusing the same idempotency key and command returns the same import; reusing it with different fields returns 409 idempotency_conflict. A name or repository-root conflict also returns 409 and identifies the existing agent when available. The source remains linked after import. Its source_profile, source_profile_version, and review_fingerprint describe the reviewed source identity. A later GitHub push that touches the selected production root automatically creates the next deployment. If that root no longer matches the imported source profile, the link status becomes source_profile_changed; no build starts and the current active revision remains unchanged.

Deploy

TypeScript SDK
REST API
oc CLI

Call	Purpose
`oc.agents.deployments.create(id, { input, activate?, idempotencyKey? })`	Deploy (`input.type: "inline" \| "github"`).
`oc.agents.deployments.list(id)` · `.get(id, depId)`	Deployment history · one deployment.
`oc.agents.deploy(dir)` (Node)	Bundle a local directory → inline deployment.

Method · Path	Purpose
`POST /agents/:id/deployments`	Deploy → `{ deployment }`. Body: `{ input, activate?=true, idempotency_key?, client_context? }`.
`GET /agents/:id/deployments?before=&limit=`	Newest-first history with an opaque `next_cursor`.
`GET /agents/:id/deployments/:deploymentId`	One attempt; poll asynchronous states until terminal.
`GET /agents/:id/deployments/:deploymentId/logs?after=&limit=`	Ordered durable log chunks with opaque resume cursors.

Command	Purpose
`oc agent deploy [dir] [--agent <id\|name>] [--no-activate]`	Bundle a local directory → inline deployment.
`oc agent build --dir <dir> [--check-only] [--target cloudflare] [--output <dir>]`	Validate or build a Flue artifact without fetching, installing, authenticating, or deploying.
`oc agent deployments [--agent <id>]` · `oc agent deployments get <id>`	History · one deployment.

input: { type:"inline", prompt, model?, skills?, runtime? } (the complete built-in behavior — omitted skills = none) or { type:"github", ref?, sha? } (deploys an already-linked repository; repo/path come from the server-owned link). activate:false stages an inline built-in deployment. Built-in GitHub links remain branch-driven. A new Flue repository agent instead starts with POST /agents/import; import deploys the reviewed production head, and subsequent production-branch pushes deploy automatically. Flue has no preview/staged Worker. POST …/revisions is inline-only sugar. Deployment

Field	Notes
`id` `created_at` `updated_at`	Attempt identity and timestamps.
`state` `phase` `terminal`	Internal state plus stable UI phase. Repository states: `accepted`, `queued`, `fetching`, `validating`, `installing`, `building`, `uploading`, `deploying`, `verifying`; terminals: `ready`, `failed`, `canceled`, `superseded`, `skipped`.
`result` `error_class` `error?`	Terminal outcome and bounded, redacted failure detail.
`revision_id` `revision?` `active`	Successful revision relation; absent for an unsuccessful attempt.
`source_relation?`	Repository id/name, path, production ref, exact SHA, and commit URL.
`build?` `configuration?`	Safe builder/artifact metadata and non-secret runtime configuration; variables are names only.
`timing`	Accepted/started/finished coordinates plus queue/run/total durations.
`log_bytes` `log_truncated`	Bounded log accounting.
`live_touched` `agent_live?`	Whether deployment crossed the live Worker boundary and the current guarded/verified state.
`allowed_actions`	Server-derived actions such as `view_commit`, `deploy_latest`, `open_agent`, or `start_session`.

List returns { data, next_cursor }. Log reads return { data: [{ seq, cursor, recorded_at, phase, stream, chunk }], next_cursor, has_more }; treat seq and both cursors as opaque strings. Continue with after=next_cursor until has_more is false, then poll again while the deployment is nonterminal. Source archives, bundles, credentials, raw provider responses, and operator telemetry are never projected through these APIs.

Revisions, rollback & promote

TypeScript SDK
REST API
oc CLI

Call	Purpose
`oc.agents.revisions.list(id)` · `.get(id, n)`	History · one revision (+ skill manifest).
`oc.agents.revisions.activate(id, n)`	Set the active revision (rollback or promote).
`oc.agents.activations.list(id)`	Active-pointer audit log.

Method · Path	Purpose
`GET /agents/:id/revisions` · `…/:rev`	History · one revision (+ skill manifest).
`POST /agents/:id/revisions/:rev/activate`	Set the active revision (rollback / promote).
`GET /agents/:id/activations`	Active-pointer audit log.

Command	Purpose
`oc agent revisions [--agent <id>]` · `oc agent revisions get <n>`	History · one revision.
`oc agent rollback <n\|rev_…>`	Set the active revision (rollback / promote).
`oc agent activations`	Active-pointer audit log.

Revisions are linear (numbered, immutable). :rev is a number or rev_… id. Activate moves the active pointer instantly (no rebuild); rollback (earlier) and promote (a staged one) are the same call. Revision

Field	Notes
`id` `number` `created_at` `active`	id, monotonic number, timestamp, is-active flag
`prompt` `model`	the behavior
`skill_bundle_digest?`	content-addressed skills bundle (`null` = no skills)
`digest`	behavior content hash (change detection)
`runtime_ref`	`floating` (latest shared runtime) — `pinned` later (custom runtime)
`files?`	`[{ path, mode, size }]` — only on `GET …/revisions/:rev`

Skills

TypeScript SDK
REST API
oc CLI

Call	Purpose
`oc.agents.skills.get(id)`	List the active revision’s skills (name, description, files).
`oc.agents.skills.put(id, zip)`	Replace skills from a `.zip` → new revision.
`oc.agents.skills.delete(id)`	Remove all skills → new revision.

Method · Path	Purpose
`GET /agents/:id/skills`	List the active revision’s skills.
`PUT /agents/:id/skills`	Replace skills from a `.zip` (`Content-Type: application/zip`) → new revision.
`DELETE /agents/:id/skills`	Remove all skills → new revision.

Command	Purpose
`oc agent deploy <dir>`	Deploy a directory; a `skills/` folder inside it ships as skills → new revision.

Skills have no dedicated CLI verb yet — deploy a directory that contains a skills/ folder, or use the REST endpoints / dashboard.

A skill is a folder with a SKILL.md; PUT/DELETE are deployments (versioned, rollback-able). Limits: 64 files, 256 KiB total, UTF-8, modes 0644/0755. Full guide: Skills.

Deploy from a repo

TypeScript SDK
REST API
oc CLI

Call	Purpose
`oc.agents.deploymentSource.link(id, params)`	Link a repo directory → push-to-deploy.
`oc.agents.deploymentSource.get(id)`	The link + status.
`oc.agents.deploymentSource.unlink(id)`	Remove the link (shared App webhook untouched).

Method · Path	Purpose
`POST /agents/:id/deployment-source`	Link a repo directory. Body: `{ repo, path, production_ref?, deploy_now?=true }`.
`GET /agents/:id/deployment-source`	The link + status.
`DELETE /agents/:id/deployment-source`	Remove the link.

Command	Purpose
`oc agent link <owner/repo> --path <p> [--branch <ref>] [--no-deploy]`	Link a repo directory.
`oc agent status [id\|name]`	The agent’s active revision + link status.
`oc agent unlink`	Remove the link.

Linking deploys the current production HEAD immediately (unless deploy_now: false / --no-deploy). The link is unique by owner, repository, and normalized root. Unlinking stops deploy-on-push but does not delete the agent, revisions, deployment history, or sessions. For built-in runtimes, a push to the production branch activates while other branches stage. For Flue, only the production branch deploys. Scopes: deploy_now: false needs agents:link; the default (with an initial deploy) needs agents:link + agents:deploy, plus agents:activate when that deploy auto-activates. Repo/path are server-anchored to the link. Deployment sources use the OpenComputer App (no BYO). Full flow + guarantees: Deploy from a repo. DeploymentSource

Field	Notes
`agent_id` `repo_id` `path`	the linked agent · repo · directory within it
`production_ref`	branch that auto-activates on push
`status`	`active`, or a problem: `source_profile_changed`, `path_missing`, `ref_missing` (production branch deleted), `auth_required`, `repo_not_selected`, `app_suspended`, `error`
`latest_seen_sha?` `active_deployed_sha?`	newest sha observed · sha behind the active revision
`source_profile?` `source_profile_version?`	server-selected repository interpretation pinned for this link (`flue-app-v1`, version `1`)
`review_fingerprint?`	digest of the latest accepted, exact-SHA reviewed plan; never source bytes or a credential

Schedules

Run an agent on a cron — each firing starts a session. Managed with the SDK, the oc CLI, or REST (org key). Full guide: Schedules.

TypeScript SDK
REST API
oc CLI

Call	Purpose
`oc.agents.schedules.create(id, params)`	Create a schedule (`{ name, cron, tz?, input, overlap? }`).
`oc.agents.schedules.list(id)` · `.get(id, sid)`	List / fetch.
`oc.agents.schedules.update(id, sid, params)`	Edit `cron`/`tz`/`input`/`overlap`, or `{ paused }`.
`oc.agents.schedules.delete(id, sid)`	Delete (run history kept).
`oc.agents.schedules.fire(id, sid)`	Fire now → a run; doesn’t advance the cron.
`oc.agents.schedules.runs(id, sid, { cursor?, limit? })`	Run history (each carries `sessionId`).

Method · Path	Purpose
`POST /agents/:id/schedules`	Create → `201 { schedule }`. Body `{ name, cron, tz?, input, overlap? }`.
`GET /agents/:id/schedules` · `…/:sid`	List / fetch.
`PATCH /agents/:id/schedules/:sid`	Edit `cron`/`tz`/`input`/`overlap`, or `{ paused }`.
`DELETE /agents/:id/schedules/:sid`	Delete → `204` (runs kept).
`POST /agents/:id/schedules/:sid/fire`	Fire now → `201 { run }`; doesn’t advance the cron.
`GET /agents/:id/schedules/:sid/runs?cursor=&limit=`	Run history → `{ runs, next_cursor }`.

Command	Purpose
`oc agent schedule create <name> --agent <id> --cron <c> [--tz <z>] --input <s>`	Create a schedule.
`oc agent schedules [--agent <id>]` · `oc agent schedule get <name>`	List / fetch.
`oc agent schedule pause\|resume <name>`	Pause / resume.
`oc agent schedule delete <name>`	Delete.
`oc agent schedule fire <name>`	Fire now (prints the `ses_…`).
`oc agent schedule runs <name>`	Run history.

cron is a 5-field expression (1-minute floor); tz is an IANA name (UTC if omitted); input (≤ 32 KiB) is the first message of every run; overlap is skip (default) or allow. Schedules are also synced from agent.toml on deploy — a repo-driven agent rejects edits other than pause/resume (409). Max 20 per agent. Schedule

Field	Notes
`id` `agent_id`	`sch_…` · the owning agent
`name` `cron` `tz?` `input`	handle (unique per agent) · 5-field cron · IANA tz · first message
`overlap`	`skip` (default) · `allow`
`state`	`active · paused · auto_paused` (five straight scheduled-firing failures auto-pause)
`next_fire_at` `last_fired_at?`	next occurrence · last fire
`consecutive_failures` `last_error?`	in-a-row enactment failures · last error (cleared on success)

Run — one per firing decision, newest-first: srn_… with outcome (enacted · skipped · failed), scheduled_for? (null for a manual fire), fired_at, session_id? (when enacted), error?. Chain session_id into GET /sessions/:id.

Slack

Managed Slack uses the OpenComputer-operated app. Starting authorization returns a browser-safe Slack OAuth URL, or the current active connection when the agent is already connected. The optional deployment id is validated return context, not a redirect URL. Status responses never contain credentials.

TypeScript SDK
REST API

Call	Purpose
`oc.agents.authorizeManagedSlack(id, { returnDeploymentId? })`	Start managed-app OAuth.
`oc.agents.getManagedSlack(id)`	Read workspace, app identity, state, and `openUrl`.
`oc.agents.listManagedSlackConnections()`	List this owner’s current workspace claims and owning agents before OAuth.
`oc.agents.disconnectManagedSlack(id)`	Stop routing this agent without uninstalling the workspace app.

Method · Path	Purpose
`POST /agents/:id/slack/managed/authorize`	Start managed-app OAuth; accepts `return_deployment_id?`.
`GET /agents/:id/slack/managed`	Read the managed connection.
`DELETE /agents/:id/slack/managed`	Disconnect the agent from the shared app.
`GET /slack/managed/connections`	List current owner-scoped workspace claims with safe agent id/name projections.

The managed status is active, disconnected, error, or revoked. An active response includes workspace, app, open_url, and connected_at; error states expose only a stable error_code. The connection list returns { data }; each item has the same public status shape plus agent: { id, name }. It contains no Slack token, signing secret, or credential reference. Treat it as a preflight convenience: authorization still enforces the one-workspace-to-one-agent claim transactionally. Builder-owned Slack apps remain a separate resource and can overlap during an explicit handoff:

TypeScript SDK	REST API
`oc.agents.slackManifest(id)`	`POST /agents/:id/slack/manifest`
`oc.agents.connectSlack(id, values)`	`POST /agents/:id/slack`
`oc.agents.getSlack(id)`	`GET /agents/:id/slack`
`oc.agents.disconnectSlack(id)`	`DELETE /agents/:id/slack`

See Slack for installation, trust boundaries, and conversation behavior.

Destinations

Webhooks are configured via SDK/REST (no oc command).

TypeScript SDK
REST API

Call	Purpose
`session.destinations.create(params)`	Register a webhook destination.
`session.destinations.list()` · `.get(did)`	List / fetch.
`session.destinations.update(did, params)`	Pause/resume (`enabled`), retune `level`/`types`, rotate `secret`.
`session.destinations.delete(did)`	Remove.

Method · Path	Purpose
`POST /sessions/:id/destinations`	Register a webhook destination.
`GET /sessions/:id/destinations` · `…/:did`	List / fetch.
`PATCH /sessions/:id/destinations/:did`	Pause/resume, retune, rotate.
`DELETE /sessions/:id/destinations/:did`	Remove.

Destination body: url, secret?, level? (user), types?[], include_raw? (false, SDK: includeRaw), enabled? (true). types accepts exact types or prefix.*.

Deliveries

Delivery records are read via SDK/REST (no oc command).

TypeScript SDK
REST API

Call	Purpose
`session.deliveries.list(opts)`	List deliveries — status, attempts, last response/error.
`session.deliveries.get(id)`	One delivery, in detail.
`session.deliveries.redeliver(id)`	Re-send any delivery.

Method · Path	Purpose
`GET /sessions/:id/deliveries?destination=&status=&after=&limit=`	List deliveries.
`GET /sessions/:id/deliveries/:id`	One delivery.
`POST /sessions/:id/deliveries/:id/redeliver`	Re-send any delivery.

See Webhooks for signing, retries, dedupe. Destination

Field	Notes
`id` `session` `kind` `created_at` `updated_at`
`url`	webhook target
`level` `types`	visibility threshold · event-type filter
`include_raw` `enabled` `has_secret`	include raw bodies · paused/active · whether a signing secret is set
`created_after_seq`	only events after this seq are delivered

Delivery

Field	Notes
`id` `session` `destination` `created_at` `updated_at`
`event_id` `event_seq`	the event delivered
`status` `attempts` `last_attempt_at`	delivery state, retry count, last try
`response_code?` `error?`	last response · failure detail

GitHub Apps and Repos

A GitHub App lets OpenComputer mint short-lived, repo-scoped tokens; a Repo is a stable handle resolving to your configured App (the OpenComputer App by default). Used for session sources (work repos) and deploy-from-a-repo (the agent’s definition repo). Install the OpenComputer App. Bring-your-own Apps apply to session sources / PR publishing (your users acting on their own repos) — deployment sources always use the OpenComputer App.

TypeScript SDK
REST API
oc CLI

Call	Purpose
`oc.repos.create(params)` · `.get(id)` · `.list()` · `.update(id, params)`	Register / fetch / list / rename a repo.
`oc.github.apps.list()`	List GitHub Apps available to your org.
`oc.github.apps.register(params)`	Register your own App (`byo_stored_key` / `byo_broker`).
`oc.github.apps.createManifestUrl(params)`	One-click: a link to open; OpenComputer hosts the flow + key capture.
`oc.github.apps.createManifest/completeManifest(params)`	Developer-driven manifest flow.
`oc.github.apps.update(id, params)` · `delete(id)`	Update / rotate / remove an App.
`oc.github.installations.list()`	List installations visible to OpenComputer.

Method · Path	Purpose
`POST /repos` · `GET /repos/:id` · `GET /repos` · `PATCH /repos/:id`	Register / fetch / list / rename a repo.
`GET /github/apps` · `POST /github/apps`	List · register your own App.
`PATCH /github/apps/:id` · `DELETE /github/apps/:id`	Update / rotate / remove.
`POST /github/apps/manifest` · `…/manifest/start` · `…/callback` · `…/conversions`	Manifest flow (hosted or developer-driven).
`GET /github/installations`	List installations visible to OpenComputer.

Command	Purpose
`oc repo add <owner/repo>` · `oc repo list` · `oc repo get <id>`	Register / list / fetch a repo.
(App install + manifest — browser flow; manage in the dashboard or via SDK/REST)

Repo body: owner, repo, provider? (github), name? — no auth (resolves via your App); idempotent by (provider, owner, repo). Registering is optional under the OpenComputer App (reference "owner/repo" directly). Responses never carry a token/secret; App responses have id, mode, status, github_app_id?, app_name?, is_default?. Guide.

Repo = { id, provider, owner, repo, name?, created_at, updated_at }

Credentials

TypeScript SDK
REST API
oc CLI

Call	Purpose
`oc.credentials.create(params)`	Add a provider key.
`oc.credentials.list()` · `oc.credentials.delete(id)`	List / remove.
`oc.credentials.setDefault(params)`	Set the org default.

Method · Path	Purpose
`POST /credentials`	Add a provider key.
`GET /credentials` · `DELETE /credentials/:id`	List / remove.
`PUT /credentials/default`	Set the org default (provider derived).

Command	Purpose
`oc credential add --provider <p> --key <k> [--default]`	Add a provider key.
`oc credential list` · `oc credential remove <id>`	List / remove.
`oc credential set-default <id>`	Set the org default.

Credential body: provider (anthropic | openai), key, name?, is_default?. Keys are write-only. A BYO credential is optional — agents can run Managed (credential: "managed", the default). See Credentials.

Credential  = { id, provider, name?, last4, is_default, created_at }
ClientToken = { token, scopes, expires_at }

Errors & rate limits

One envelope: { "error": { "type", "message" } }; the SDK throws typed OpenComputerError subclasses (AuthError, NotFoundError, ConflictError, ValidationError, RateLimitError); the CLI exits non-zero and prints the message (the JSON with --json). Cross-owner resources return 404 (not 403). Rate/concurrency limits aren’t enforced at launch (a 429 with Retry-After may come later; the SDK retries it).

Getting Started

Sandboxes

Browser Sessions

Durable Agent Sessions

Reserved Capacity

CLI

Guides

TypeScript SDK

Python SDK

CLI Reference

API Reference

Resources

API / SDK / CLI reference

Sessions

Events

Steer

Watches

Agents

Deployments and revisions

Review and import a repository agent

Deploy

Revisions, rollback & promote

Skills

Deploy from a repo

Schedules

Slack

Destinations

Deliveries

GitHub Apps and Repos

Credentials

Errors & rate limits

​Sessions

​Events

​Steer

​Watches

​Agents

​Deployments and revisions

​Review and import a repository agent

​Deploy

​Revisions, rollback & promote

​Skills

​Deploy from a repo

​Schedules

​Slack

​Destinations

​Deliveries

​GitHub Apps and Repos

​Credentials

​Errors & rate limits

Sessions

Events

Steer

Watches

Agents

Deployments and revisions

Review and import a repository agent

Deploy

Revisions, rollback & promote

Skills

Deploy from a repo

Schedules

Slack

Destinations

Deliveries

GitHub Apps and Repos

Credentials

Errors & rate limits