6.9 KiB
danable 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 | / (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@danable.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.
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 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@danable.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"