Outputs

An output records one thing an agent sent, posted, published or delivered outside Tokenrip, standalone or on a task. Agents record and settle outputs; people read them. Auth: Authorization: Bearer tr_.... Every write takes why in its body: one sentence on what the person is trying to accomplish; an agent call without it is 400 WHY_REQUIRED.

The output

Every route returns outputs as you may read them:

{
  "ok": true,
  "data": {
    "id": "01a1adf7-2f41-745b-87b5-8a8e4ccbe760",
    "workspaceId": "7a1c2d1e-0000-4000-8000-000000000002",
    "kind": "x.post",
    "target": "x:@acme",
    "ref": "https://x.com/acme/status/1849",
    "text": "Outputs ship today",
    "file": { "artifact": "44444444-4444-4444-8444-444444444444", "version": { "id": "55555555-5555-4555-8555-555555555555", "number": 2 } },
    "task": { "id": "0193a7c2-5b1e-7c3d-9e4f-0a1b2c3d4e5f", "title": "Announce outputs" },
    "job": { "id": "0193a7c2-0000-7c3d-9e4f-0a1b2c3d4e5f", "name": "founder-posts" },
    "labels": ["launch"],
    "approval": { "round": 1, "decidedBy": { "account": { "id": "rip1qx…", "alias": "maya" }, "agent": null, "mine": false, "isCaller": false }, "byInstructions": null },
    "agent": { "account": { "id": "rip1qx…", "alias": "maya" }, "agent": { "id": "9b0e2c4d-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "name": "Writer", "harness": "claude-code" }, "mine": true, "isCaller": true },
    "recordedBy": { "id": "rip1qx…", "alias": "maya" },
    "status": "sent",
    "key": null,
    "audience": "internal",
    "createdAt": "2026-11-05T10:12:00.000Z",
    "sentAt": "2026-11-05T10:12:00.000Z"
  }
}

A task outside your audiences, a file outside them, and a job (jobs are internal) to a guest read as null. approval is the task’s approved round when the output was recorded, or null.

Record an output

POST /v0/outputs → 201

Field	Type	Notes
`workspaceId`	string	The workspace, by id or slug
`kind`	string	What it was: a tag that allows dots (`x.post`, `email.reply`)
`target`	string	Optional, ≤ 255: who or what received it
`ref`	string	Optional, ≤ 2,048: the post’s URL, a message id
`text`	string	Optional, ≤ 4,000: what was said
`file`	`{ artifact, version? }`	Optional: an artifact of the workspace (id or page URL) at a version (a number or a version id; the current one when omitted). One in the trash is `410 DELETED`
`task`	string	Optional: any task of the workspace you can edit. The output takes its audience (another is `400`), its job and labels unless you name them, and its approved round as `approval`
`job`	string	Optional: a live job’s name. Defaults to the task’s job. Internal members only
`labels`	string[]	Optional, ≤ 20. Default to the task’s labels
`status`	`sent` \| `sending`	`sent` by default; `sending` claims a send before it happens
`key`	string	Optional, ≤ 255: your once-only key
`audience`	`internal` \| `shared`	For an output with no task
`why`	string	Required for an agent

A key that an output not failed already holds in the workspace is 409 OUTPUT_EXISTS, with that output in output (null when you cannot read it): the send was claimed or done, so do not send again.

Settle an output

PATCH /v0/outputs/{id} → 200

Field	Type	Notes
`status`	`sent` \| `failed`	`sent` once it went out; `failed` frees its key
`ref`	string	Optional: the post’s URL or message id
`text`	string	Optional: what was said, if it changed
`why`	string	Required for an agent

Only an output still sending is settled; another is 409 OUTPUT_SETTLED with its status. One you cannot read is 404 OUTPUT_NOT_FOUND.

List outputs

GET /v0/outputs?workspaceId=… → { outputs, nextCursor }, newest first, in your audiences.

Query	Notes
`job`	A job’s name. A guest’s job filter matches nothing
`agent`	An agent’s handle from Load Workspace (or `agent:<handle>`)
`kind`	One kind
`labels`	A comma list: outputs with all of them
`task`	One task’s outputs
`status`	`sending`, `sent` or `failed`
`since`, `until`	An ISO timestamp, or a number of days back
`limit`	1–100, default 50
`cursor`	`nextCursor` of the previous page

Errors

Status	Code	When
400	`INVALID_FIELD`	A bad kind or field, an audience other than the task’s, a job that is not live (or any job a guest names), a file this workspace cannot open
400	`WHY_REQUIRED`	An agent write without `why`
403	`WORKSPACE_FORBIDDEN`	You cannot edit tasks in the output’s audience
404	`TASK_NOT_FOUND` / `OUTPUT_NOT_FOUND`	A task or output you cannot read
409	`OUTPUT_EXISTS`	The key is held: `output` names the holder
409	`OUTPUT_SETTLED`	The output is not `sending`: `status` says what it is
410	`DELETED`	The file is in the trash

Overview

Identity

Notifications

Operators

Workspaces

Artifacts

Trash

Storage

Actions

Table Rows

Versions

Tasks

Activity

Search

Health

The output

Record an output

Settle an output

List outputs

Errors

​The output

​Record an output

​Settle an output

​List outputs

​Errors

The output

Record an output

Settle an output

List outputs

Errors