Projects

The projects resource is the write side of the datasets 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.

from pictograph import Client
client = Client()

list / iter

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

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

create

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.

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

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

{
  "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