> 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/projects-api.md).

# Projects API

{% hint style="info" %}
**Outcome:** Create, list, retrieve, update, and delete Projects with explicit state checks.
{% endhint %}

### Endpoints

| Method | Endpoint                          | Purpose                                                  |
| ------ | --------------------------------- | -------------------------------------------------------- |
| GET    | `/api/sdk/projects/`              | List visible Projects                                    |
| POST   | `/api/sdk/projects/`              | Create a Project; optionally attach a Workspace Ontology |
| GET    | `/api/sdk/projects/{project_id}/` | Retrieve one Project                                     |
| PATCH  | `/api/sdk/projects/{project_id}/` | Change name or description                               |
| DELETE | `/api/sdk/projects/{project_id}/` | Soft-delete and schedule cleanup                         |

### Create a Project

```bash
curl --fail-with-body --silent --show-error \
  -X POST "$UNITLAB_API_URL/api/sdk/projects/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"Road-scene review","ontology_hash":"ONTOLOGY_HASH"}'
```

Store response field `pk` as `PROJECT_ID`. Project data, Workflow, and Release routes all require it.

### Retrieve and update

```bash
curl --fail-with-body --silent --show-error \
  "$UNITLAB_API_URL/api/sdk/projects/PROJECT_ID/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY"

curl --fail-with-body --silent --show-error \
  -X PATCH "$UNITLAB_API_URL/api/sdk/projects/PROJECT_ID/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"Road-scene review v2","description":"Night and rain cohort"}'
```

Verify `pk`, name, description, `ontology_hash`, and `number_of_data`.

### Delete boundary

Before DELETE, resolve the exact Project ID and check attached sources, open tasks, and downstream Releases. A timeout does not prove deletion failed; retrieve the Project before repeating the request.

### 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 %}