Overview

The SDK exposes 22 resource groups under client.<resource>. Each method maps 1:1 to a REST endpoint. Use the SDK for type safety and auto-retry; use raw REST from other languages.

from pictograph import Client

client = Client()   # reads PICTOGRAPH_API_KEY

Each page below shows the same operation on every surface it supports, in this order: Python, then the pictograph CLI, then raw REST. REST examples authenticate with an X-API-Key header, so setting PICTOGRAPH_API_KEY in your shell makes them copy-and-run.

Resources

Resource	Purpose	CLI group
Datasets	Full dataset lifecycle - CRUD, archive, insights, bulk download, cold storage	datasets
Images	Single-image upload / download / delete	images
Annotations	Per-image annotation read / save / delete	annotations
Annotation comments	Review comments pinned to a single annotation	none
Auto-annotate	SAM3 point / box / text / batch prompts	auto-annotate
Search	Tag and similarity search across a dataset	search
Batch	Bulk move / copy / delete / update on images	none
Exports	Dataset exports in 12 formats (COCO, YOLO, Pascal VOC, CVAT, …)	exports
Training	Spawn and monitor training runs	train
Models	Versions, artifacts, downloads, and inference	models
Model evaluations	Score a model against an export - P/R/F1, mAP, confusion matrix	none
Deployments	Stand a model up as a live inference endpoint, billed by uptime	deployments
Workflows	DAG workflows over images, video, or a dataset	workflows
Webhooks	Signed, retried outbound event delivery	webhooks
Credits	Balance, ledger, pre-flight cost estimation	credits
Connectors	V7 / Roboflow dataset import	connectors
Video	Video upload + frame extraction	video
Organizations	Members and invites for the active org	organizations
Notifications	The organization event feed - poll what finished	notifications
Directories	Read a dataset’s virtual directory tree and per-directory stats	directories
Tasks	Annotation tasks + per-annotator contribution breakdown (audit / billing export)	tasks
API keys	Programmatic key management	none
Tools	Agent tool registry (JSON Schema reference)	agents
Result models	Every object the SDK returns, generated from the shipped package	-

Every resource supports Python and REST. The CLI additionally exposes augment, tile, and metrics, which wrap SDK helpers rather than a resource of their own.

Helpers that chain several calls

A few multi-step flows have a one-call method on the resource that owns them. Each walks the collection, polls the job, and returns a report instead of raising on one bad item.

Method	Chains
client.images.upload_from_directory	walk directory → bulk upload
client.auto_annotate.dataset	list images → batch SAM3 → save
client.images.tile	download → slice into a grid → upload tiles
client.images.augment	download → augment → upload variants
client.training.create	train a completed export

Each is also exposed as an agent tool.

Conventions across resources

• Name-based lookups are preferred (get(name=...)). UUID variants exist where useful (get_by_id(...)).
• Pagination: .list() returns one page; .iter() returns an OffsetPager that auto-fetches subsequent pages.
• Long-running ops (training, exports, batch SAM3, dataset imports) default to wait=True and poll until terminal. Pass wait=False to fire-and-forget.
• Failure reports: bulk operations return per-item failure lists rather than raising on the first error.
• Idempotency: mutating operations auto-generate an Idempotency-Key header, so a retried call is not applied twice.