Ultralytics Platform

REST API at https://platform.ultralytics.com, auth Authorization: Bearer ul_.... Interactive spec: GET /openapi.json (needs the bearer header).

The auth shape and the four gotchas below were run against the live API on 2026-08-04. Endpoint shapes not covered by those runs come from /openapi.json and are marked unverified in references/.

Get the key first

export ULTRALYTICS_API_KEY=ul_... # Settings > API Keys on platform.ultralytics.com

The ultralytics package reads ULTRALYTICS_API_KEY env first, then api_key in settings.json (yolo settings api_key=ul_...). Check both before assuming the key is missing.

Pick the path before writing any code

Package callback (live runs)

Set the key and pass project=, then train normally. ultralytics/utils/callbacks/platform.py streams per-epoch metrics, system metrics, console output, PR/F1/confusion-matrix plots, and uploads best.pt at the end.

model.train(data="coco8.yaml", epochs=100, project="my-project", name="run1")

project= is mandatory. The callback returns early without it, so no key and no project= both produce the same silent nothing. That is the #1 cause of "I trained but the platform is empty". See references/recipes.md for the full enablement gate and the other failure modes.

ul:// URIs

Resolve to signed URLs inside data= and model=, no manual download:

YOLO("ul://username/my-project/my-model").train(data="ul://username/datasets/my-dataset", epochs=100)

REST

Read references/recipes.md before writing a request. It carries working code for retro upload of a finished run, dataset upload and download, search, cloud training, export, deployment, and cleanup. Each section states whether it was run live or derived from the spec.

references/api-reference.md is the endpoint table plus the request shapes.

Four things that break first-time requests

1. POST /api/models and GET /api/models need the 24-char project ID, not the slug. Every other endpoint accepts a slug in the path. These two return 400 Invalid project ID for a slug even though the parameter is documented as "name or ID". Create the project first and keep the returned projectId.
2. Top-level metrics is a closed key set, listed in references/api-reference.md. Posting a raw results.csv key like metrics/mAP50-95(B) returns 400 Unrecognized key. trainResults[].metrics is free-form, so csv rows go in there as is.
3. Uploads are three calls, not one. POST /api/upload/signed-url to get the URL, plain PUT of the bytes to that URL with no auth header, then POST /api/upload/complete. Skipping the third call leaves the file unattached.
4. Deletes are soft. DELETE /api/projects/{id} moves to trash and cascades to its models. DELETE /api/trash/empty makes it permanent.

Cost and destructive actions

POST /api/training/start, POST /api/exports, and POST /api/deployments spend credits. The cost comes back in the create response, not from a lookup beforehand, so report billing.estimatedCostDisplay from the POST result before letting the job run. Confirm with the user before any create-with-cost or any delete.