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

# Update Artifact

> PATCH /v0/artifacts/:publicId — Change an artifact's title, description, alias, metadata, folder, visibility, or workspace audience

Change an artifact's metadata without publishing a new version. Only the fields you send change. To change content, [publish a version](/api-reference/versions/publish).

CLI equivalents: `rip artifact patch` (title, description, alias, metadata, visibility, audience) and `rip artifact move` (folder).

**Auth:** `Authorization: Bearer tr_...`

* **Standalone artifact** — the owner, or a member of a team the artifact is shared with.
* **Workspace artifact** — a workspace member who can edit its content; changing `audience` needs audience-management rights. The workspace must not be archived.

## Path parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `publicId` | string | Yes | Artifact public ID or alias |

## Request body

| Field | Type | Description |
| - | - | - |
| `title` | string | New title, 1–256 characters after trimming |
| `description` | string | New description, up to 2000 characters. An empty string clears it. |
| `alias` | string | New alias: 3–128 lowercase letters, digits and hyphens, starting and ending with a letter or digit. An empty string clears it. |
| `metadata` | object | Replaces the existing metadata object |
| `folderId` | string \| null | File into this folder (ID), or `null` to unfile. A workspace artifact can only go into a folder of the same workspace; a standalone artifact into your own or a team folder you belong to (filing into a team folder also shares the artifact with that team). |
| `visibility` | string | Standalone artifacts only: `private`, `link`, or `public`. See [Sharing & Access](/concepts/sharing-and-access). |
| `embeddingEnabled` | boolean \| null | Opt this artifact in or out of semantic-search indexing; `null` inherits the default |
| `audience` | string | Workspace artifacts only: `internal` or `shared` |
| `expectedWorkspaceRevision` | integer | **Required** for workspace artifacts: the artifact's current `workspaceRevision` |
| `workspaceSessionId` | string | Workspace artifacts only: attribute the change to your live [workspace session](/api-reference/workspaces/load) |

<CodeGroup>
  ```bash Standalone theme={null}
  curl -X PATCH https://api.tokenrip.com/v0/artifacts/8f14e45f-ceea-467a-9a3e-1b2c3d4e5f60 \
    -H "Authorization: Bearer tr_..." \
    -H "Content-Type: application/json" \
    -d '{ "title": "Q3 Plan", "visibility": "link" }'
  ```

  ```bash Workspace theme={null}
  curl -X PATCH https://api.tokenrip.com/v0/artifacts/8f14e45f-ceea-467a-9a3e-1b2c3d4e5f60 \
    -H "Authorization: Bearer tr_..." \
    -H "Content-Type: application/json" \
    -d '{ "audience": "shared", "expectedWorkspaceRevision": 4 }'
  ```
</CodeGroup>

## Example response

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "8f14e45f-ceea-467a-9a3e-1b2c3d4e5f60",
    "title": "Q3 Plan",
    "description": null,
    "alias": "q3-plan",
    "metadata": {},
    "folder_id": null,
    "isPublic": false,
    "visibility": "link",
    "embeddingEnabled": null,
    "updatedAt": "2026-09-29T10:00:00.000Z"
  }
}
```

A workspace artifact's response also includes `workspaceId`, `audience`, and the new `workspaceRevision`. Every workspace update increments the revision and records an `artifact.updated` (or `artifact.audience_changed`) entry in the [workspace change feed](/api-reference/workspaces/changes).

## Errors

| Status | Error code | Condition |
| - | - | - |
| 400 | `INVALID_TITLE` | `title` is empty or longer than 256 characters |
| 400 | `INVALID_DESCRIPTION` | `description` is longer than 2000 characters |
| 400 | `INVALID_ALIAS` | `alias` breaks the alias rules or is reserved |
| 400 | `INVALID_VISIBILITY` | `visibility` is not `private`, `link`, or `public`, or a public asset was set to `private` |
| 400 | `INVALID_SCOPE` | `audience` was sent for a standalone artifact |
| 400 | `INVALID_INPUT` | `audience` is not `internal` or `shared` |
| 400 | `PRECONDITION_REQUIRED` | Workspace artifact without `expectedWorkspaceRevision` |
| 403 | `NOT_OWNER` | You don't own the standalone artifact (and no team share grants access), or you tried to file into another agent's folder |
| 403 | `NOT_A_MEMBER` | Target team folder belongs to a team you are not in |
| 403 | `WORKSPACE_ARTIFACT_FORBIDDEN` | Your workspace role can't make this change |
| 404 | `NOT_FOUND` / `FOLDER_NOT_FOUND` | The artifact or target folder doesn't exist or isn't visible to you |
| 409 | `ALIAS_CONFLICT` | The alias is already in use |
| 409 | `CONFLICT` | `expectedWorkspaceRevision` is stale; the body includes `currentWorkspaceRevision` |
| 409 | `WORKSPACE_AUTHORITY` | `visibility` was sent for a workspace artifact — use `audience` |
| 409 | `CROSS_WORKSPACE_MOVE` | The target folder is in a different workspace |
| 409 | `FOLDER_CHANGED` | The artifact's folder changed concurrently — retry |
| 409 | `WORKSPACE_ARCHIVED` | The workspace is archived |