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

# Prune Versions

> DELETE /v0/artifacts/{artifactId}/versions — Delete an artifact's old versions, keeping the current one

Delete an artifact's old versions in one call, keeping the current version and the newest `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](/api-reference/versions/delete.md): for a standalone artifact, only the owner; for a [workspace](/concepts/workspaces.md) 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

Send `Content-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](/api-reference/workspaces/overview.md#why-on-every-write) |

## Example request

```bash cURL theme={null}
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

```json theme={null}
{
  "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 |

A version's stored file is deleted only when no other version still uses it: a [fork](/api-reference/artifacts/fork.md) shares its source version's file, so forking keeps it. In a workspace, a prune that removed versions advances the artifact's `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 |


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