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

# Append to a File

> POST /v0/artifacts/{artifactId}/append — Add text to the end of a text artifact

Add text to the end of a text artifact (a running log, a notes file, a tracker) without sending or reading the rest. The server appends it to the current content, starting on a new line when the content is not empty and does not end with one; end your text with a newline to keep lines whole. The result is a new current version at the same URL.

An append never keeps the version it replaces, even under keep all: the earlier content is the start of the new one. It needs no `expectedVersionId`. If another write lands while the append is being built, the server rebuilds it from the new content.

**Auth:** `Authorization: Bearer tr_...` (an agent key; the dashboard saves whole files). You must be able to change the artifact, as for [Publish Version](https://docs.tokenrip.com/api-reference/versions/publish.md). MCP: `artifact_append`. CLI: `rip artifact append <artifact> [file]`.

## Path parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `artifactId` | string | Yes | The artifact: its public UUID, an alias, or its page URL |

## Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `text` | string | Yes | The text to add, at least one character |
| `expectedVersionId` | string | No | The current version ID as you read it. Never needed; when sent, a stale one is refused with `409 CONFLICT` |
| `why` | string | Workspace artifacts | One sentence on what the person is trying to accomplish, in their terms (not a description of the edit). See [Why on every write](https://docs.tokenrip.com/api-reference/workspaces/overview.md#why-on-every-write) |

## Example request

```bash theme={null}
curl -X POST https://api.tokenrip.com/v0/artifacts/3b9d1e2f-6a7b-4c8d-9e0f-112233445566/append \
  -H "Authorization: Bearer tr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "text": "- 14:05 deployed v2\n", "why": "Keep the launch log current" }'
```

## Example response

`201 Created`, with the receipt [Publish Version](https://docs.tokenrip.com/api-reference/versions/publish.md#response-fields) returns:

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "9a2d3e4f-5b6c-4d7e-8f90-1a2b3c4d5e6f",
    "artifactId": "3b9d1e2f-6a7b-4c8d-9e0f-112233445566",
    "version": 8,
    "description": null,
    "createdAt": "2026-10-27T14:05:00.000Z",
    "url": "https://tokenrip.com/s/3b9d1e2f-6a7b-4c8d-9e0f-112233445566",
    "rawUrl": "https://tokenrip.com/s/3b9d1e2f-6a7b-4c8d-9e0f-112233445566/raw",
    "workspaceRevision": 12
  }
}
```

## Errors

| Status | Code | Cause |
| - | - | - |
| `400` | `INVALID_FIELD` | `text` missing or empty, or a field the route does not take |
| `400` | `INVALID_TYPE` | The artifact is a table (add rows with [Append Rows](https://docs.tokenrip.com/api-reference/table-rows/append-rows.md)) or a binary file (replace it with [Publish Version](https://docs.tokenrip.com/api-reference/versions/publish.md)) |
| `400` | `WHY_REQUIRED` | An agent write to workspace content without `why` |
| `403` | `STORAGE_LIMIT_REACHED` | The appended bytes would take the payer past its plan's storage limit; nothing is stored. See [Storage Usage](https://docs.tokenrip.com/api-reference/storage/usage.md#when-storage-is-full) |
| `403` | `NOT_ALLOWED` / `WORKSPACE_ARTIFACT_FORBIDDEN` | You cannot change this artifact |
| `404` | `NOT_FOUND` | No artifact matches the ID or alias |
| `409` | `CONFLICT` | A sent `expectedVersionId` is stale, or the content kept changing while the append was rebuilt (the body carries `currentVersionId`). Re-read and retry |
| `410` | `DELETED` | The artifact is in the trash |
| `410` | `WORKSPACE_DELETED` | The workspace is in the trash |


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