> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/api-sdk-cli/apis/releases-api.md).

# Releases API

{% hint style="info" %}
**Outcome:** Create versioned Project exports, inspect metadata, and request annotation or source downloads.
{% endhint %}

### Endpoints

| Method | Endpoint                                   | Purpose                                  |
| ------ | ------------------------------------------ | ---------------------------------------- |
| GET    | `/api/sdk/releases/`                       | List Releases                            |
| GET    | `/api/sdk/releases/{release_id}/`          | Retrieve Release metadata                |
| POST   | `/api/sdk/projects/{project_id}/releases/` | Create a Project snapshot                |
| POST   | `/api/sdk/releases/{release_id}/`          | Prepare an annotation or source download |

### Create a Release

```bash
curl --fail-with-body --silent --show-error \
  -X POST "$UNITLAB_API_URL/api/sdk/projects/PROJECT_ID/releases/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "export_type":"UUEF",
    "split_ratios":{"train":80,"validation":20},
    "include_download_tokens":false,
    "upload_sessions":["BATCH_QUEUE_ID"],
    "generic_types":["img","video"],
    "bundle_formats":{"img":"COCO","video":"UUEF"}
  }'
```

![Project release configuration dialog](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FHLzEBrP9ddsrTUbQ4ovz%2Frelease-create-modal.png?alt=media\&token=70baced4-91a7-4c40-bf7b-417177d75b90)

*The request preserves approved queue scope, data types, formats, split distribution, source handling, and token policy.*

Read the Release back and verify `pk`, version, item count, data type, formats, and visibility.

### Request a download

```bash
curl --fail-with-body --silent --show-error \
  -X POST "$UNITLAB_API_URL/api/sdk/releases/RELEASE_ID/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"download_type":"annotation","split_type":"train"}'
```

Annotation downloads return a temporary file URL. File downloads can return inline content or per-file URLs. Treat signed URLs as secrets, validate destination paths, and verify the artifact before downstream use.

### Request operating contract

| Concern           | Required behavior                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| Execution surface | TLS-verified client using the reviewed current public `/api/sdk/...` route contract.                  |
| Identity          | Least-privilege workspace service identity; secrets remain outside code and logs.                     |
| Request boundary  | URL-encoded stable IDs, explicit deadlines, structured errors, and complete pagination.               |
| Success evidence  | Response identifiers, read-after-write verification, and separate processing status for Batch Queues. |

{% hint style="warning" %}
Do not infer undocumented private routes. After a timeout, inspect remote state before repeating a mutation.
{% endhint %}