Update Artifact
curl --request PATCH \
--url https://api.example.com/v0/artifacts/:artifactIdimport requests
url = "https://api.example.com/v0/artifacts/:artifactId"
response = requests.patch(url)
print(response.text)const options = {method: 'PATCH'};
fetch('https://api.example.com/v0/artifacts/:artifactId', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v0/artifacts/:artifactId",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v0/artifacts/:artifactId"
req, _ := http.NewRequest("PATCH", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.example.com/v0/artifacts/:artifactId")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/artifacts/:artifactId")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
response = http.request(request)
puts response.read_bodyArtifacts
Update Artifact
PATCH /v0/artifacts/:artifactId — Change an artifact’s title, description, alias, metadata, folder, visibility, or history setting
PATCH
/
v0
/
artifacts
/
:artifactId
Update Artifact
curl --request PATCH \
--url https://api.example.com/v0/artifacts/:artifactIdimport requests
url = "https://api.example.com/v0/artifacts/:artifactId"
response = requests.patch(url)
print(response.text)const options = {method: 'PATCH'};
fetch('https://api.example.com/v0/artifacts/:artifactId', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v0/artifacts/:artifactId",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v0/artifacts/:artifactId"
req, _ := http.NewRequest("PATCH", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.example.com/v0/artifacts/:artifactId")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/artifacts/:artifactId")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
response = http.request(request)
puts response.read_bodyChange an artifact’s metadata or history setting without publishing a new version. Only the fields you send change; send at least one. An unknown field is
A workspace artifact’s response also includes
400 INVALID_FIELD naming it (folderId and isPublic are not fields: use folder and visibility). To change content, publish a version.
CLI equivalents: rip artifact patch (title, description, alias, metadata, visibility, --history) 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 (
writeContent); changingvisibilityneedsshare. Editors and admins hold both.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
artifactId | string | Yes | The artifact’s id, an alias (bare, ~agent/alias or _team/alias), or its page URL (URL-encoded in the path) |
Request body
| Field | Type | Description |
|---|---|---|
title | string | New title, 1–255 characters after trimming |
description | string | New description, up to 64,000 characters. An empty string clears it. |
alias | string | null | New alias: 3–128 lowercase letters, digits and hyphens, starting and ending with a letter or digit. null clears it. |
metadata | object | null | Replaces the existing metadata object, except that a table keeps its schema and strict unless you send them (null keeps only those two). On a table, a schema that differs from the stored one is validated as at create, except that the column names it keeps from the stored schema are not checked again: existing tables can hold names create refuses. A new name, and the key column’s name, follow the column-name rule. A new schema that declares, moves or removes the key re-keys the stored rows in the same call |
folder | string | null | File into this folder: its id, or a slug (in the artifact’s workspace, else in team, else one of your personal folders); null unfiles it. 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). |
team | string | With a folder slug only: the team (slug or id) the folder belongs to |
visibility | string | Standalone artifacts: private, link, or public. Workspace artifacts: private (members only) or link (public access: anyone with the URL reads the file, with no login, by direct read; never listed or searched). public on a workspace artifact is 400 INVALID_VISIBILITY. Earlier versions become readable too; prune them first if they shouldn’t be. See Sharing & Access. |
history | 'off' | 'all' | integer | null | How many earlier versions this artifact’s whole-file updates and edits keep: off, all, or the last n (1–100). null clears it, so it follows its folder, then its workspace (off by default). Changing it deletes nothing; it applies from the next write. Not on a table. The response carries the effective history: { value, from }. See History |
expectedWorkspaceRevision | integer | The artifact’s current workspaceRevision. Required on a workspace artifact when the patch sets description or metadata (it was composed from what you read); otherwise optional. A stale one is 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). Required on an agent write, except a patch of visibility alone (a why you send is still recorded); at most 300 characters. See Why on every write |
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" }'
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": "Q4 plan", "expectedWorkspaceRevision": 4, "why": "Keep the plan easy to find for the launch review" }'
curl -X PATCH https://api.tokenrip.com/v0/artifacts/8f14e45f-ceea-467a-9a3e-1b2c3d4e5f60 \
-H "Authorization: Bearer tr_..." \
-H "Content-Type: application/json" \
-d '{ "visibility": "link" }'
Example response
{
"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",
"updatedAt": "2026-09-29T10:00:00.000Z"
}
}
workspaceId and the new workspaceRevision. Every workspace update increments the revision and records what it changed in the workspace change feed: artifact.moved for a folder change, artifact.details_changed for title, description, alias, metadata or history, then artifact.public_access_granted or artifact.public_access_removed when public access changed, each with the same why. A visibility patch naming the current value writes nothing: no revision, no change. A new version (see Publish Version) records artifact.edited.
Errors
| Status | Error code | Condition |
|---|---|---|
400 | WHY_REQUIRED | An agent write to workspace content without why |
403 | STORAGE_LIMIT_REACHED | A longer description would take the artifact’s payer past its plan’s storage limit. Long text counts; a shorter one never is |
| 400 | INVALID_FIELD | The body names the field and lists the accepted ones: an unknown field, an empty change, title empty or longer than 256 characters, description longer than 64,000 characters, alias breaking the alias rules or reserved, visibility not private, link or public, audience (refused with “Sharing is by workspace now: everyone in a workspace sees all of it. Keep private work in a separate workspace.”), or history not off, all, a whole number from 1 to 100, or null |
| 400 | INVALID_TYPE | history on a table: “Tables have rows, not versions: a table takes no history setting.” Nothing changes |
| 400 | INVALID_VISIBILITY | A public asset was set to private, or a workspace artifact was set to public |
| 400 | INVALID_SCHEMA | A table’s new metadata.schema fails create’s validation (a stored name it keeps is not checked again): for example a column without a type, an enum without values, a column property other than name, type, values, unique, sensitive and position, an enum value holding U+0000 or a lone surrogate, a duplicate name, a new name (or the key column’s) that breaks the column-name rule, unique other than true or false, or unique: true on more than one column. Nothing in the call is written |
| 400 | INVALID_METADATA | A table’s metadata is not an object or null |
| 400 | INVALID_SCHEMA | The new key column holds an object or array value, or a value longer than 1024 bytes (the body names the column, never the value). Nothing changes |
| 400 | PRECONDITION_REQUIRED | Workspace artifact patch of description or metadata 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. When an artifact in the trash holds it, the body carries details: { inTrash: true, purgeAt } |
| 409 | CONFLICT | expectedWorkspaceRevision is stale; the body includes currentWorkspaceRevision |
| 409 | DUPLICATE_UNIQUE_VALUE | The new schema declares or moves the key onto a column whose stored values repeat. The body carries column and a repeated value (null for a sensitive column); nothing changes |
| 409 | WORKSPACE_AUTHORITY | folder names a workspace folder for a standalone artifact: workspace content is filed through its workspace |
| 409 | CROSS_WORKSPACE_MOVE | The target folder is in a different workspace |
| 409 | FOLDER_CHANGED | The artifact’s folder changed concurrently — retry |
| 410 | DELETED | The artifact, or its folder, is in the trash |
| 410 | WORKSPACE_DELETED | The workspace is in the trash |