# Manage Trash

Projects and dataset versions moved to Trash are retained for 30 days before being permanently cleaned up. You can delete, list, and restore items through the REST API; permanent deletion is web-UI only (see the [Permanent Deletion](#permanent-deletion) note at the bottom).

In-flight training jobs for a project or version are automatically cancelled when the item is moved to Trash.

## Delete a Project

{% tabs %}
{% tab title="REST API" %}
Move a project to Trash:

```url
https://api.roboflow.com/:workspace/:project
```

```bash
curl "https://api.roboflow.com/my-workspace/my-detector?api_key=$ROBOFLOW_API_KEY" \
  -X DELETE
```

Example response:

```json
{
  "deleted": true,
  "type": "project",
  "workspace": "my-workspace",
  "project": "my-detector",
  "projectId": "d_abc123",
  "trash": true
}
```

The calling API key must have the `project:update` scope.
{% endtab %}
{% endtabs %}

## Delete a Version

{% tabs %}
{% tab title="REST API" %}
Move a single dataset version to Trash:

```url
https://api.roboflow.com/:workspace/:project/:version
```

```bash
curl "https://api.roboflow.com/my-workspace/my-detector/3?api_key=$ROBOFLOW_API_KEY" \
  -X DELETE
```

Example response:

```json
{
  "deleted": true,
  "type": "version",
  "workspace": "my-workspace",
  "project": "my-detector",
  "projectId": "d_abc123",
  "version": "3",
  "trash": true
}
```

The calling API key must have the `version:update` scope.
{% endtab %}
{% endtabs %}

## Delete a Workflow

{% tabs %}
{% tab title="REST API" %}
Move a workflow to Trash:

```url
https://api.roboflow.com/:workspace/workflows/:workflowUrl
```

```bash
curl "https://api.roboflow.com/my-workspace/workflows/slow-webhooks?api_key=$ROBOFLOW_API_KEY" \
  -X DELETE
```

Example response:

```json
{
  "deleted": true,
  "type": "workflow",
  "workspace": "my-workspace",
  "workflow": "slow-webhooks",
  "workflowId": "wf_abc123",
  "trash": true
}
```

The calling API key must have the `workflow:update` scope.
{% endtab %}
{% endtabs %}

## List Items in Trash

{% tabs %}
{% tab title="REST API" %}
List everything currently in the workspace Trash:

```url
https://api.roboflow.com/:workspace/trash
```

```bash
curl "https://api.roboflow.com/my-workspace/trash?api_key=$ROBOFLOW_API_KEY"
```

Example response:

```json
{
  "items": [
    {
      "type": "project",
      "id": "d_abc123",
      "name": "My Detector",
      "url": "my-detector",
      "deletedAt": "2026-04-20T17:05:33.000Z",
      "scheduledCleanupAt": "2026-05-20T17:05:33.000Z",
      "deletedBy": "uid-of-user",
      "deletedByName": "Alice"
    },
    {
      "type": "version",
      "id": "3",
      "name": "augmented-416",
      "parentId": "d_xyz789",
      "parentName": "My Other Project",
      "parentUrl": "my-other-project",
      "parentInTrash": false,
      "deletedAt": "2026-04-21T12:14:02.000Z",
      "scheduledCleanupAt": "2026-05-21T12:14:02.000Z"
    }
  ],
  "sections": {
    "projects": [ ... ],
    "versions": [ ... ],
    "workflows": [ ... ]
  }
}
```

Each item includes a `scheduledCleanupAt` timestamp — the point at which the item is eligible for permanent cleanup. Projects also carry a `cleanupDeleteImages` boolean indicating whether images exclusive to the project will be deleted along with it when cleanup runs.

The calling API key must have the `project:read` scope.
{% endtab %}
{% endtabs %}

## Restore an Item

{% tabs %}
{% tab title="REST API" %}
Restore a project, version, or workflow from Trash:

```url
https://api.roboflow.com/:workspace/trash/restore
```

```bash
curl "https://api.roboflow.com/my-workspace/trash/restore?api_key=$ROBOFLOW_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"type": "project", "id": "d_abc123"}'
```

For versions, you must also include the parent project id:

```bash
curl "https://api.roboflow.com/my-workspace/trash/restore?api_key=$ROBOFLOW_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"type": "version", "id": "3", "parentId": "d_abc123"}'
```

Restoring a version requires the parent project to still be active (not itself in Trash). If the parent is also in Trash, restore it first.

`type` must be one of `project`, `version`, or `workflow`. The required API-key scope is **per-type** — the request fails with 401 if the key doesn't carry the right scope for the item being restored:

| `type`     | Required scope    |
| ---------- | ----------------- |
| `project`  | `project:update`  |
| `version`  | `version:update`  |
| `workflow` | `workflow:update` |

The endpoint also verifies that `targetItem.owner === :workspace` before delegating, so a key valid in workspace A cannot restore an item that lives in workspace B.
{% endtab %}
{% endtabs %}

## Permanent Deletion

Permanent deletion is intentionally not available on the REST API. The actions to empty Trash and to immediately delete a single Trash item destroy data irrecoverably, and we don't want a stray curl or automation to be able to trigger them. These actions are available only through the Trash view in the Roboflow web app.

Items left in Trash are cleaned up automatically after the 30-day retention window.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roboflow.com/developer/rest-api/manage-trash.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.