9 KiB
danagble API reference
Base URL: http://localhost:8000/api/v1 (prefix from config.yaml app.api_prefix).
Interactive docs: http://localhost:8000/docs.
Conventions
- Auth:
Authorization: Bearer <accessToken>on every endpoint except those marked Public.GET /auth/loginwith wrong credentials returns 401 and the frontend redirects to/login. - Tracing headers (optional in, always out): send
X-Session-ID(one ID per browser visit; server mints one if absent) and optionallyX-User-Id. Responses echoX-Session-IDand a per-requestX-Trace-ID. - Errors are JSON
{ detail: string }. Common codes:400bad input,401missing/invalid token,404unknown id,409slug/email conflict,422validation,503R2 not configured (.envkeys missing). - Enums:
taskType:classification | object_detection | segmentation; imagestatus:unassigned | in_progress | pending_review | completed; shapetype:bbox | polygon | point.
System (Public)
| Method | Path | Description |
|---|---|---|
| GET | /health |
Liveness incl. DB check, { ok: true } |
| GET | /metrics |
Phase-1 traffic counters per route |
| GET | /storage/usage |
Real bucket { bytes, objects, quota_bytes } (10-min cache) |
| GET | / (root, no prefix) |
Name, docs and health links |
| POST | /admin/init-db |
Create tables, seed dev admin. Dev-only |
| POST | /admin/backfill-thumbnails?limit=100 |
Mint missing thumbs. Dev-only |
Auth (Public)
POST /auth/login — body { email, password } — returns:
{
"user": { "id": "...", "name": "Admin", "email": "admin@danagble.local",
"avatarInitials": "A", "avatarColor": "#3B82F6",
"role": "admin", "status": "active",
"isOnline": true, "lastActive": "..." },
"accessToken": "<jwt ~12h>",
"refreshToken": "<jwt 7d>"
}
GET /auth/me (auth) — current user in the same shape.
Users (auth)
| Method | Path | Body | Description |
|---|---|---|---|
| GET | /users |
— | All users { id, email, name, role, status, assignedProjectIds } |
| POST | /users |
{ email, role, projectIds? } |
Invite (unusable password until set), 201 |
| PATCH | /users/{id} |
{ role?, status?, projectIds? } |
Role / suspend / project assignment |
Roles: admin | manager | annotator | reviewer. Status:
active | invited | suspended (suspended tokens are rejected).
Projects (auth)
| Method | Path | Description |
|---|---|---|
| GET | /projects |
Full project cards: stats, classes, members, thumbnailUrl |
| POST | /projects |
{ name, slug, description?, taskType }, 201 |
| GET | /projects/{id} |
Detail (same card shape) |
| PATCH | /projects/{id} |
{ name?, slug?, description?, task_type?, status? } |
| DELETE | /projects/{id} |
Cascades images, annotations, classes, exports, AI and action rows |
| POST | /projects/{id}/classes |
{ name, color?, shortcutKey? }, 201 |
| PUT | /projects/{id}/classes |
Bulk replace [{ id?, name, color }] (matches LabelsTab semantics) |
stats example: { totalImages, unassigned, inProgress, pendingReview, completed, totalObjects }. members are users assigned to the project with
per-member assignedCount.
Images (auth)
Direct-to-R2 upload keeps bytes and bandwidth off the API:
POST /projects/{id}/images/presign{ fileName, contentType }→{ putUrl, r2Key }(900s TTL).PUT <putUrl>with the file bytes (Content-Typemust match).POST /projects/{id}/images{ fileName, r2Key, width?, height? }→201 { id, r2Key, url }. Confirm verifies the object exists, writes the metadata row and mints 512px + 128px thumbnails (fail-open).
GET /projects/{id}/images is paginated — never the whole dataset:
GET /projects/{id}/images?status=all&search=img_&assignee=all&limit=50&offset=0
→ { "items": [ ... ], "total": 1000 }
limit clamps to 1..200 (config max_page_size). Item fields: id,
projectId, fileName, url, thumbnailUrl (512px), thumbnailSmallUrl
(128px, falls back up the chain), width/height, status, objectCount,
assignedTo/assignedToName, reviewerName, classificationLabelId, flags.
PATCH /projects/{id}/images/{imageId}?status=completed — status transition.
POST /projects/{id}/images/batch-presign — one call for ≤200 files:
[{ fileName, contentType }] → [{ fileName, putUrl, r2Key }]
(keys carry unique tmp ids, so duplicate filenames never collide).
GET /projects/{id}/images/by-id/{imageId} — { offset, total } in list
order (deterministic created_at DESC, id DESC); backs ?imageId= deep
links into thousand-image datasets.
Resumable multipart uploads (files ~100MB and up)
Small files keep the single-PUT presign path. Big single files (GB zips, TIFF, video) go multipart, straight to R2:
POST /projects/{id}/uploads/multipart{ fileName, contentType }→{ key, uploadId, partSize: 8388608 }.POST .../uploads/multipart/parts{ key, uploadId, numbers: [1..N] }→{ urls: { "1": "...", ... } }(1h TTL each).- PUT every part (parallel, per-part retry; store ETags client-side — the upload resumes after network drops instead of restarting).
POST .../uploads/multipart/complete{ key, uploadId, parts: [{ ETag, PartNumber }] }→{ key, etag }.POST .../uploads/multipart/abortto cancel and free the upload.
ETag response headers are exposed via the bucket CORS policy, which the frontend needs to read them.
Server-side dataset imports (GB-scale zips)
POST /projects/{id}/imports/local-zip { path } (absolute server path)
or POST /projects/{id}/imports/r2-zip { r2_key } (zip already uploaded,
e.g. via multipart) → 202 { id, status: queued, ... }. The worker streams
the archive (one image in RAM at a time), uploads originals + 512/128px
thumbs concurrently, commits DB rows in batches, then bulk-upserts COCO
annotations. Re-running skips files already present.
GET /projects/{id}/imports and GET /projects/{id}/imports/{jobId} poll
{ status, total_files, done_files, saved_annotations, error }.
Annotations (auth)
GET /projects/{pid}/images/{iid}/annotation — one row per image:
{ "imageId": "...", "projectId": "...", "classificationLabelId": "cls-1",
"flags": { "blurryOrUncertain": false, "needsRecheck": false },
"shapes": [{ "id": "s1", "index": 1, "type": "bbox",
"labelId": "cls-1", "labelName": "car", "color": "#ff0000",
"visible": true, "bbox": { "x": 10, "y": 20, "width": 100, "height": 80 } }] }
PUT /projects/{id}/annotations/batch with { [imageId]: { classificationLabelId?, flags?, shapes[] } }
upserts up to 500 images in one commit (COCO/YOLO import path) →
{ saved, missing: [...] }.
PUT same path with { classificationLabelId?, flags?, shapes[] } upserts
(one row per image, 404 when the image does not exist) and syncs
object_count / flags onto the image row. Also emits an annotation.save
action event. Polygon shapes use points: [{x, y}], points use point.
Events and activities
POST /events (Public, 202) — client-side actions the backend never sees:
{ "session_id": "…", "events": [
{ "action": "image.status", "project_id": "…", "image_id": "…",
"payload": { "from": "a", "to": "b" } } ] }
session_id is required; max 200 events/call. Enqueued to Redis and drained
into action_events (requeued on DB failure, never lost, never blocks).
GET /activities?limit=30 (auth) — human feed derived from that table:
[{ id, timestamp, userName, actionText, projectId }].
Worked example (curl)
B=http://localhost:8000/api/v1
curl -s -X POST $B/admin/init-db
TOK=$(curl -s -X POST $B/auth/login -H 'Content-Type: application/json' \
-d '{"email":"admin@danagble.local","password":"Admin123!"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['accessToken'])")
H="Authorization: Bearer $TOK"
PID=$(curl -s -X POST $B/projects -H "$H" -H 'Content-Type: application/json' \
-d '{"name":"Pho Co","slug":"pho-co","description":"e2e","taskType":"classification"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
# upload one image
PRE=$(curl -s -X POST $B/projects/$PID/images/presign -H "$H" \
-H 'Content-Type: application/json' -d '{"fileName":"s.jpg","contentType":"image/jpeg"}')
PUTURL=$(echo "$PRE" | python3 -c "import sys,json; print(json.load(sys.stdin)['putUrl'])")
R2KEY=$(echo "$PRE" | python3 -c "import sys,json; print(json.load(sys.stdin)['r2Key'])")
curl -s -o /dev/null -w "%{http_code}\n" -X PUT -H 'Content-Type: image/jpeg' \
--data-binary @photo.jpg "$PUTURL"
IID=$(curl -s -X POST $B/projects/$PID/images -H "$H" -H 'Content-Type: application/json' \
-d "{\"fileName\":\"s.jpg\",\"r2Key\":\"$R2KEY\",\"width\":1280,\"height\":720}" \
| python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
# classify + complete
curl -s -X PUT $B/projects/$PID/images/$IID/annotation -H "$H" \
-H 'Content-Type: application/json' -d '{"shapes":[],"flags":{}}'
curl -s -X PATCH "$B/projects/$PID/images/$IID?status=completed" -H "$H"