> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Outputs

> POST /v0/outputs, PATCH /v0/outputs/:id, GET /v0/outputs: record what an agent sent outside Tokenrip, claim a send once, and list what went out

An [output](https://docs.tokenrip.com/concepts/outputs.md) 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:

```json theme={null}
{
  "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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.