Skip to content

API.md

Latest commit

 

History

History
301 lines (235 loc) · 5.69 KB

API.md

File metadata and controls

301 lines (235 loc) · 5.69 KB
Raw

API Reference — Cradle AI Backend

Base URL: http://localhost:8000 (production: your-render-url.com)

All endpoints use REST with JSON. CORS enabled for frontend origins.

✅ Health & Status

GET /health

Quick health check.

Response:

{
  "status": "healthy"
}

📹 Video Upload & Processing

POST /api/upload

Upload a video file for analysis.

Headers:

Content-Type: multipart/form-data

Form Data:

  • file (required): Video file (MP4 or MOV)

Response (201 Created):

{
  "video_id": "550e8400-e29b-41d4-a716-446655440000",
  "analysis_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "filename": "nursery_night.mp4",
  "size_bytes": 10485760,
  "message": "Video queued for processing"
}

Errors:

  • 400: Invalid file format, unsupported content-type, or empty file
  • 413: File too large (max 500MB)
  • 500: Server error during save

GET /api/upload/{video_id}/status

Get processing status of a queued/processing video.

Response:

{
  "video_id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "nursery_night.mp4",
  "status": "processing",
  "progress_percent": 45,
  "current_step": "Analyzing frames with GPT-5.6"
}

Status Values:

  • queued — Waiting to process
  • processing — Currently analyzing
  • completed — Done, call /api/analysis/{id}
  • error — Failed

📊 Analysis Results

GET /api/analysis/{video_id}

Get completed analysis (timeline, summary, stats).

Response:

{
  "video_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "timeline": [
    {
      "time": "20:05",
      "event_type": "sleep",
      "label": "Baby fell asleep",
      "detail": "Room went quiet, no movement for 4+ min",
      "confidence": 0.95,
      "badge_type": "bg-sleep"
    },
    {
      "time": "23:45",
      "event_type": "cry",
      "label": "Crying started",
      "detail": "Duration 3m 12s",
      "confidence": 0.87,
      "badge_type": "bg-cry"
    }
  ],
  "summary": "Overall a settled night. Baby slept 7h 42m...",
  "stats": {
    "total_sleep_minutes": 462,
    "crying_episodes": 2,
    "crying_total_minutes": 8.2,
    "wake_ups": 5,
    "caregiver_visits": 1
  },
  "sleep_quality_score": 78
}

Timeline Item Properties:

  • time (string): HH:MM formatted start time
  • event_type (string): sleep, cry, movement, adult
  • label (string): Human-readable event name
  • detail (string): Additional context
  • confidence (float): 0.0–1.0 detection confidence
  • badge_type (string): CSS class for styling

⚠️ Alert Rules

Backend only — not currently exposed in the UI. This product analyzes footage after the fact rather than monitoring live, so "notify me" rule toggles would imply a capability the app doesn't have; the endpoints remain available for a future live-monitoring mode.

GET /api/alert-rules

Get current alert configuration.

Response:

{
  "rules": [
    {
      "rule_type": "crying",
      "enabled": true,
      "threshold": 30,
      "description": "Notify after sustained crying"
    },
    {
      "rule_type": "movement",
      "enabled": true,
      "threshold": null,
      "description": "Notify on repeated crib activity"
    },
    {
      "rule_type": "adult",
      "enabled": true,
      "threshold": null,
      "description": "Log every caregiver visit"
    },
    {
      "rule_type": "awake_time",
      "enabled": false,
      "threshold": 23,
      "description": "Notify if awake after 11 PM"
    }
  ]
}

POST /api/alert-rules

Update alert rules.

Request:

{
  "rules": [
    {
      "rule_type": "crying",
      "enabled": true,
      "threshold": 45,
      "description": "Notify after sustained crying"
    }
  ]
}

Response:

{
  "status": "ok",
  "message": "Alert rules updated"
}

📹 Videos List

GET /api/videos

List all uploaded videos.

Response:

{
  "videos": [
    {
      "video_id": "550e8400-e29b-41d4-a716-446655440000",
      "filename": "night_2024_01_15.mp4",
      "upload_date": "2024-01-15T22:30:45.123456",
      "status": "completed"
    }
  ]
}

🔗 CORS

Frontend can call from:

  • http://localhost:3000 (Next.js dev)
  • http://localhost:8000 (API docs)
  • http://localhost:8001 (static frontend)
  • Production domain (set in .env)

Headers Sent:

Access-Control-Allow-Origin: <origin>
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

⚡ Performance Notes

  • Video upload: Async processing in background
  • Analysis time: 30s–5min depending on video length
  • Polling: Recommended every 2 seconds
  • Max file size: 500MB (configurable)

🛠 Testing

Using cURL

# Upload
curl -X POST http://localhost:8000/api/upload \
  -F "file=@video.mp4"

# Check status
curl http://localhost:8000/api/upload/VIDEO_ID/status

# Get analysis
curl http://localhost:8000/api/analysis/VIDEO_ID

# Get alert rules
curl http://localhost:8000/api/alert-rules

# Update alert rules
curl -X POST http://localhost:8000/api/alert-rules \
  -H "Content-Type: application/json" \
  -d '{"rules": [...]}'

🐛 Error Handling

All errors return JSON with detail field:

{
  "detail": "Video not found"
}

Common HTTP Codes:

  • 200 — Success
  • 400 — Bad request (validation failed)
  • 404 — Resource not found
  • 413 — File too large
  • 500 — Server error

📖 API Documentation (Auto-Generated)

Visit http://localhost:8000/docs for interactive Swagger UI.

Visit http://localhost:8000/redoc for ReDoc documentation.