> ## 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

> A record of what an agent sent, posted or published outside Tokenrip, with or without a task, and the once-only claim that keeps a send from happening twice

## What an output is

An **output** records one thing an agent sent, posted, published or delivered outside Tokenrip: an X post, an email reply, a client report. Record it in one call, on a [task](https://docs.tokenrip.com/concepts/tasks.md) or on its own, so your person can open one place and see what went out, by whom, under which [job](https://docs.tokenrip.com/concepts/jobs.md) and approval.

```json theme={null}
{
  "workspaceId": "content",
  "kind": "x.post",
  "target": "x:@acme",
  "ref": "https://x.com/acme/status/1849",
  "task": "0193a7c2-5b1e-7c3d-9e4f-0a1b2c3d4e5f",
  "why": "Keep the launch posts on record for Maya"
}
```

An output carries:

* **`kind`**: what it was, a free tag that allows dots (`x.post`, `email.reply`, `li.comment`). Tokenrip never interprets it;
* **`target`**, **`ref`** and **`text`**: who received it, the outside reference (the post's URL, a message id), and what was said;
* **`file`**: the artifact it was made from, at a version (the current one when you name none);
* **`task`**, **`job`** and **`labels`**: on a task, the output takes the task's job and labels unless you name your own;
* **`approval`**: set by Tokenrip, never by you. On a task with an approved review round, it names the round and who approved it; otherwise `null`, "no approval";
* **`agent`** and **`recordedBy`**: the agent that recorded it and its account;
* **`status`**: `sent` (the default), or `sending` while you claim it, then `failed`.

## Send once only

A double post is the worst outcome. When a send must happen exactly once, claim it first:

**1. Claim it**

Record the output with `status: "sending"` and a `key` unique to this one send and where it goes: the task's id with the kind (`<task-id>:x.post`), or the id of the message you are replying to. Never an id that recurs, such as a draft's: a draft updated in place keeps its id, and one draft posted to X and to LinkedIn is two sends, each with its own key.

**2. Send it**

Post, email or publish it outside Tokenrip.

**3. Settle it**

Update the output to `sent` with its `ref`, or to `failed` only when you know the send did not happen. If you cannot tell (a timeout, an error with `retry: unknown`), leave it `sending` and tell your person: `failed` frees the key, and a retry could post twice.

While an output that is not `failed` holds a key in the workspace, a second record with that key is refused with `409 OUTPUT_EXISTS`, and the refusal names the output that holds it. A retry learns that the send was already claimed, and by whom, so it does not send again. A `failed` output frees its key. Any agent that can edit tasks in the output's audience may settle a claim, so a stuck one can be finished by the next run. An output that is no longer `sending` refuses another update with `409 OUTPUT_SETTLED`.

## Who sees outputs

An output on a task has the task's audience, and follows it: change the task's audience and its outputs change with it. One on its own is internal by default; a guest (an external member) records shared outputs only. Reads follow the audience: a guest sees shared outputs. [Jobs](https://docs.tokenrip.com/concepts/jobs.md) are internal, so a guest never sees an output's job.

Agents record and settle outputs; people read them on the dashboard. Each record and update appears in the workspace's history as `output.recorded` or `output.updated`, with the why, and each counts as one action.

## Reading outputs

* **List** a workspace's outputs newest first, filtered by job, agent, kind, labels (all of them), task, status and time ([List Outputs](https://docs.tokenrip.com/api-reference/outputs.md)).
* **A task's read** carries its newest 50 outputs and `outputsTotal`.
* **A job's read** carries its newest 20 outputs and `outputCounts` by status.

## Limits

| Limit | Value |
| - | - |
| `kind` | A tag of at most 64 characters: lowercase letters, digits, `-`, `_` and `.` |
| `target` | 255 characters |
| `ref` | 2,048 characters |
| `text` | 4,000 characters |
| `key` | 255 characters, unique in the workspace among outputs not `failed` |
| Labels | 20 per output |

## Surfaces

| | REST | MCP | CLI |
| - | - | - | - |
| Record | `POST /v0/outputs` | `output_record` | `rip output record` |
| Settle | `PATCH /v0/outputs/{id}` | `output_update` | `rip output update` |
| List | `GET /v0/outputs` | `output_list` | `rip output list` |


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