---
title: Projects
description: Project (dataset) write operations — create, update config (classes / annotation types), delete.
section: API Reference
order: 15
---
The **`projects`** resource is the write side of the
[`datasets`](/docs/api-reference/datasets.md) resource. Same underlying
entity; the SDK aliases the read path to "datasets" because that's the
word users say.

Use this page for: creating a project, editing its class set,
deleting it.

```python
from pictograph import Client
client = Client()
```

## list / iter

```python
projects = client.projects.list(limit=50)
for p in client.projects.iter(page_size=100):
    print(p.name, len(p.classes))
```

`Project` includes the embedded `project_config` (classes + annotation
types), unlike `Dataset` which is read-optimized for the list view.

## get

```python
project = client.projects.get("my-dataset")
for cls in project.classes:
    print(cls.name, cls.type, cls.color)
```

## create

```python
from pictograph import ProjectClass

project = client.projects.create(
    "new-dataset",
    description="Road sign detection training set",
    annotation_types=["bbox", "polygon"],
    classes=[
        ProjectClass(name="stop_sign", type="bbox", color="#ff0000"),
        ProjectClass(name="yield",     type="bbox", color="#ffff00"),
    ],
)
```

| Arg | Type | Default | Notes |
|---|---|---|---|
| `name` | `str` | required | Unique within the org |
| `description` | `str \| None` | `None` | |
| `annotation_types` | `Sequence[str]` | `["bbox"]` | Allowed types for this project |
| `classes` | `Sequence[ProjectClass \| dict]` | `[]` | Class definitions; can be added later via `update` |

Returns `Project`.

## update

Patch project metadata or its config (classes / annotation types).
Pass only the fields you're changing.

```python
client.projects.update(
    "my-dataset",
    description="Updated description",
    annotation_types=["bbox", "polygon", "polyline"],
)

# Add / remove / recolor classes:
client.projects.update(
    "my-dataset",
    classes=[
        ProjectClass(name="stop_sign", type="bbox", color="#ff0000"),
        ProjectClass(name="yield",     type="bbox", color="#ffaa00"),  # color change
        ProjectClass(name="speed_limit", type="bbox", color="#00aaff"),  # new
        # 'merge' class omitted → removed (also removes any annotations using it)
    ],
)
```

Class updates are atomic — the entire `classes` list is replaced.
Removing a class **also removes every annotation using that class
name** across the dataset. Be deliberate.

## delete

```python
result = client.projects.delete("my-dataset")
print(result["images_deleted"], result["annotations_deleted"])
```

Permanent. Removes:
- The project and its config
- Every image (and the underlying stored bytes)
- Every export tied to the project

Models trained from this project are **not** deleted (they're useful
even after the source dataset is gone).

Requires `admin`+ role.

## ProjectClass shape

```python
{
  "name": "stop_sign",
  "type": "bbox",          # "bbox" / "polygon" / "polyline" / "keypoint"
  "color": "#ff0000",      # hex color for UI rendering (any valid CSS color)
}
```

The class name must be unique within the project's class list — saves
fail with `ValidationError` if two classes share a name.

## Common errors

| Status | Exception | Cause |
|---|---|---|
| 403 | `ForbiddenError` | `delete` requires `admin`+ |
| 404 | `NotFoundError` | Project name doesn't exist |
| 409 | `ConflictError` | `create` with a duplicate name |
| 422 | `ValidationError` | Duplicate class names, invalid annotation type |