Prune Versions
curl --request DELETE \
--url https://api.example.com/v0/artifacts/{artifactId}/versionsimport requests
url = "https://api.example.com/v0/artifacts/{artifactId}/versions"
response = requests.delete(url)
print(response.text)const options = {method: 'DELETE'};
fetch('https://api.example.com/v0/artifacts/{artifactId}/versions', 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}/versions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
]);
$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}/versions"
req, _ := http.NewRequest("DELETE", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.delete("https://api.example.com/v0/artifacts/{artifactId}/versions")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/artifacts/{artifactId}/versions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
response = http.request(request)
puts response.read_bodyVersions
Prune Versions
DELETE /v0/artifacts//versions — Delete an artifact’s old versions, keeping the current one
DELETE
/
v0
/
artifacts
/
{artifactId}
/
versions
Prune Versions
curl --request DELETE \
--url https://api.example.com/v0/artifacts/{artifactId}/versionsimport requests
url = "https://api.example.com/v0/artifacts/{artifactId}/versions"
response = requests.delete(url)
print(response.text)const options = {method: 'DELETE'};
fetch('https://api.example.com/v0/artifacts/{artifactId}/versions', 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}/versions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
]);
$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}/versions"
req, _ := http.NewRequest("DELETE", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.delete("https://api.example.com/v0/artifacts/{artifactId}/versions")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/artifacts/{artifactId}/versions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
response = http.request(request)
puts response.read_bodyDelete an artifact’s old versions in one call, keeping the current version and the newest
A version’s stored file is deleted only when no other version still uses it: a fork shares its source version’s file, so forking keeps it. In a workspace, a prune that removed versions advances the artifact’s
keep of the others. Every version is stored in full and counts toward the owner’s storage, so this frees what the old versions hold.
The delete is permanent: old versions do not go to the trash. The current version always stays, so the artifact’s content does not change. Because the current version is the newest, pruning never frees a version number: the next version you publish takes the next number after it.
Auth: Authorization: Bearer tr_.... The same permission as deleting a version: for a standalone artifact, only the owner; for a workspace artifact, internal admins and editors (members who can delete workspace content); internal viewers and external members cannot.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
artifactId | string | Yes | The artifact: its public UUID, an alias, or its page URL |
Request body
SendContent-Type: application/json, or no body. A query parameter is refused with 400 INVALID_FIELD.
| Field | Type | Required | Description |
|---|---|---|---|
keep | integer | No | How many of the newest old versions to keep besides the current one. Default 0: only the current version stays |
expectedWorkspaceRevision | integer | No | Optional, for a workspace artifact: its current workspaceRevision. 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); required on an agent write to workspace content, at most 300 characters. See Why on every write |
Example request
curl -X DELETE https://api.tokenrip.com/v0/artifacts/3b9d1e2f-6a7b-4c8d-9e0f-112233445566/versions \
-H "Authorization: Bearer tr_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "keep": 2 }'
Response
{
"ok": true,
"data": {
"artifactId": "3b9d1e2f-6a7b-4c8d-9e0f-112233445566",
"removed": 37,
"freedBytes": 18350000,
"versionCount": 3
}
}
| Field | Description |
|---|---|
removed | How many versions were deleted. 0 when there was nothing beyond keep; nothing else changes then |
freedBytes | The bytes those versions held |
versionCount | How many versions the artifact has now |
workspaceRevision and records one artifact.versions_pruned change with payload: { removed, freedBytes }.
Errors
| Status | Code | Cause |
|---|---|---|
400 | INVALID_FIELD | keep is not a whole number of 0 or more, an unknown field, or a field in the query string |
400 | INVALID_TYPE | The artifact is a table: tables have rows, not versions |
400 | WHY_REQUIRED | An agent write to workspace content without why |
403 | NOT_OWNER | You do not own this standalone artifact |
403 | WORKSPACE_ARTIFACT_FORBIDDEN | Your workspace role cannot delete content in the artifact’s workspace |
404 | NOT_FOUND | No such artifact |
409 | CONFLICT | expectedWorkspaceRevision is stale. The body carries currentWorkspaceRevision |
410 | DELETED | The artifact is in the trash |
410 | WORKSPACE_DELETED | The workspace is in the trash |