HTTP API

Base URL when serving locally: http://127.0.0.1:8765.

All JSON API routes are under the /api prefix. HTML pages are separate (see below).

Tip

While the server is running you can also explore interactive OpenAPI docs if exposed by FastAPI defaults (/docs, /redoc) depending on app configuration.

Pages (HTML)

Method	Path	Description
GET	/	Dashboard
GET	/setup	Team/Enterprise first-time setup
GET	/login	Sign-in (when auth required)
GET	/orgs	Organizations
GET	/projects/new	Create / import project
GET	/projects/{project_id}	Project detail
GET	/projects/{project_id}/annotate	Annotate UI (CV or samples)
GET	/projects/{project_id}/upload	Upload images
GET	/static/...	Static assets

---

Projects

Method	Path	Body	Success
GET	/api/projects	—	ProjectOut[]
POST	/api/projects	ProjectCreate	ProjectOut 201
GET	/api/projects/{id}	—	ProjectOut
PATCH	/api/projects/{id}	ProjectUpdate	ProjectOut
DELETE	/api/projects/{id}	—	204
POST	/api/projects/bulk-delete	{ "ids": [1,2] }	{ "deleted": n }
POST	/api/projects/import	multipart	ProjectOut 201
POST	/api/projects/import/folder	ProjectImportRequest	ProjectOut 201

ProjectCreate

{
  "name": "string",
  "description": "",
  "project_type": "object_detection",
  "location": "",
  "workspace_id": null
}

workspace_id: optional parent workspace (null → Default workspace).

CV: object_detection, instance_segmentation, classification, semantic_segmentation.

Other: text_classification, ner, tabular_classification, tabular_regression, audio_classification, transcription, video_classification, action_recognition, instruction_tuning, preference, rag_eval.

---

Classes

Method	Path	Body
GET	/api/projects/{id}/classes	—
POST	/api/projects/{id}/classes	{ "name", "color?" }
DELETE	/api/classes/{class_id}	—

---

Images

Method	Path	Notes
GET	/api/projects/{id}/images	Optional ?split=
POST	/api/projects/{id}/images	multipart files
DELETE	/api/images/{image_id}	—
POST	/api/images/bulk-delete	{ "ids": [...] } (+ optional project_id)
GET	/api/projects/{id}/images/file/{filename}	raw image bytes

---

Annotations

Method	Path	Body
GET	/api/images/{image_id}/annotations	—
POST	/api/images/{image_id}/annotations	AnnotationCreate
PUT	/api/annotations/{annotation_id}	AnnotationCreate
DELETE	/api/annotations/{annotation_id}	—

AnnotationCreate

{
  "class_id": 1,
  "annotation_type": "bbox",
  "geometry": {"x": 0.1, "y": 0.2, "width": 0.3, "height": 0.4},
  "confidence": null,
  "source": "manual"
}

annotation_type: bbox, polygon, mask, classification.

---

Auto-annotate

Method	Path	Body
POST	/api/projects/{id}/auto-annotate/yolo	{ "model", "confidence", "iou", "image_ids?" }
POST	/api/projects/{id}/auto-annotate/sam	{ "image_id", "class_id", "points", "labels" }

---

Splits, versions, pipeline defaults

Method	Path	Body / query
POST	/api/projects/{id}/splits	`?train=70&valid=20&test=10&strategy=random
GET	/api/projects/{id}/versions	—
POST	/api/projects/{id}/versions	VersionCreate
GET	/api/pipeline/defaults	—

---

Plugins & pipelines

Method	Path	Notes
GET	/api/plugins	optional plugin_type
GET	/api/plugins/{type}/{name}	single plugin
GET	/api/pipelines/step-types	known step types
GET	/api/pipelines/example	PPE example definition
POST	/api/pipelines	create (empty definition → example)
GET	/api/pipelines	optional project_id
GET/PUT/DELETE	/api/pipelines/{id}	CRUD
POST	/api/pipelines/validate	JSON definition
POST	/api/pipelines/validate-yaml	YAML text
POST	/api/pipelines/from-yaml	create from YAML
GET	/api/pipelines/{id}/yaml	export YAML
POST	/api/pipelines/{id}/run	{ project_id?, version_id? }
GET	/api/pipelines/{id}/runs	run history
GET	/api/pipeline-runs/{id}	one run

See Pipelines and plugins.

---

Text & tabular samples

Method	Path	Notes
GET/POST	/api/projects/{id}/samples	list / create
GET/PATCH	/api/samples/{id}	get / label / spans / value
POST	/api/projects/{id}/import/text	JSONL or CSV upload
POST	/api/projects/{id}/import/tabular	CSV upload
POST	/api/projects/{id}/import/jsonl	audio / video / LLM JSONL
POST	/api/projects/{id}/samples/splits	stratified sample splits
POST	/api/projects/{id}/adapters/prepare	sklearn / huggingface prepare
POST	/api/projects/{id}/adapters/train	sklearn train

See Text and tabular modalities and Audio, video, and LLM datasets.

---

Export

Method	Path	Body
POST	/api/projects/{id}/export	{ "format", "version_id?", "include_unannotated" }
GET	/api/exports/{filename}	download

format: coco → COCO JSON; yolo → YOLO zip; jsonl → text; csv → tabular.

---

Models & training

Method	Path	Notes
GET	/api/models	optional project_id
GET	/api/projects/{id}/models	registered
POST	/api/projects/{id}/models	register from path
POST	/api/projects/{id}/models/upload	multipart upload
DELETE	/api/models/{model_id}	—
GET	/api/models/runs	discover run weights
GET	/api/system/device	CUDA / default device
POST	/api/projects/{id}/train	TrainRequest
GET	/api/projects/{id}/train/status	active / latest / idle
GET	/api/train/jobs/{job_id}	job JSON

TrainRequest

{
  "version_id": 1,
  "model": "yolov8n.pt",
  "epochs": 50,
  "imgsz": 640,
  "batch": 16,
  "device": "auto",
  "require_ready": true,
  "min_readiness_score": 60
}

Set require_ready to false to bypass the readiness gate.

---

Identity & collaboration

Method	Path	Notes
GET	/api/auth/me	Current user
POST	/api/auth/login	{ email, password }
POST	/api/auth/register	{ email, password, display_name? }
POST	/api/auth/logout	—
GET/POST/DELETE	/api/auth/tokens	API tokens
GET	/api/identity/roles	Role catalog
GET/POST	/api/orgs	Organizations
GET/POST	/api/projects/{id}/members	Project members
GET/POST	/api/projects/{id}/assignments	Image assignments
GET/POST	/api/projects/{id}/reviews	Review queue / submit
POST	/api/reviews/{id}/decide	Approve / reject / changes
GET/POST/DELETE	/api/images/{id}/lock	Soft sample lock
GET	/api/annotations/{id}/revisions	Annotation history

---

Setup (Team / Enterprise)

Method	Path	Notes
GET	/api/setup/status	Whether setup is required
POST	/api/setup	Complete first-time admin / org bootstrap

See Deployment modes & plugins and Deploy with Docker.

---

Platform

Method	Path	Notes
GET	/api/health	Liveness
GET	/api/ready	DB (+ Redis) readiness
GET	/api/quality/checks	Check catalog + defaults (?modality=)
GET	/api/cleaning/actions	Cleaning action catalog (?modality=)
GET	/api/projects/{id}/profile	Dataset profile (image or sample)
GET	/api/projects/{id}/quality	Quality report (defaults)
POST	/api/projects/{id}/quality	Quality report with config
POST	/api/projects/{id}/readiness	Training readiness (config + adapter)
POST	/api/projects/{id}/cleaning/preview	Dry-run cleaning
POST	/api/projects/{id}/cleaning	Apply cleaning actions
GET	/api/projects/{id}/canonical	Universal sample schema export
GET	/api/projects/{id}/experiments	List experiments
GET	/api/experiments/{id}	Experiment detail
PATCH	/api/experiments/{id}	Update name / tags / notes
POST	/api/experiments/compare	{ "ids": [1, 2] }
PATCH	/api/models/{id}/lifecycle	{ "lifecycle": "production" }
GET	/api/training/adapters	Adapter registry

---

Stats

GET /api/stats

{
  "project_count": 0,
  "total_images": 0,
  "annotated_images": 0,
  "total_annotations": 0
}

---

Example: create → upload → annotate (curl)

# Create project
curl -s http://127.0.0.1:8765/api/projects \
  -H "Content-Type: application/json" \
  -d '{"name":"demo","project_type":"object_detection"}'

# Add class (use returned project id)
curl -s http://127.0.0.1:8765/api/projects/1/classes \
  -H "Content-Type: application/json" \
  -d '{"name":"object","color":"#14b8a6"}'

# Upload images
curl -s http://127.0.0.1:8765/api/projects/1/images \
  -F "files=@image1.jpg" -F "files=@image2.jpg"