-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathopenapi_spec.json
More file actions
1 lines (1 loc) · 45.1 KB
/
openapi_spec.json
File metadata and controls
1 lines (1 loc) · 45.1 KB
1
{"openapi":"3.1.0","info":{"title":"VideoAnnotator API","description":"Production-ready REST API for video annotation processing","version":"1.3.0"},"paths":{"/api/v1/health":{"get":{"tags":["health"],"summary":"Health check with optional detailed diagnostics","description":"Check API server liveness and optionally retrieve detailed system status.\n\n**Basic mode** (default): Returns simple 200 OK for load balancers.\nFast response, minimal overhead.\n\n**Detailed mode** (?detailed=true): Returns comprehensive diagnostics including:\n- Database connectivity and job count\n- Storage disk space and warnings\n- GPU availability and memory\n- Pipeline registry status\n\nDetailed mode returns 503 status if critical subsystems are unhealthy.\n\n**Example Requests:**\n\nBasic (fast):\n```bash\ncurl -X GET \"http://localhost:18011/api/v1/health\"\n```\n\nDetailed (diagnostic):\n```bash\ncurl -X GET \"http://localhost:18011/api/v1/health?detailed=true\" \\\n -H \"X-API-Key: your-api-key-here\"\n```","operationId":"health_check_api_v1_health_get","parameters":[{"name":"detailed","in":"query","required":false,"schema":{"type":"boolean","description":"Include detailed diagnostics (slower response)","default":false,"title":"Detailed"},"description":"Include detailed diagnostics (slower response)"}],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{},"examples":{"basic":{"summary":"Basic health check (fast)","value":{"status":"ok","version":"1.3.0","timestamp":"2025-10-22T12:00:00.000Z"}},"detailed":{"summary":"Detailed health check","value":{"status":"ok","version":"1.3.0","timestamp":"2025-10-22T12:00:00.000Z","details":{"database":{"status":"ok","message":"Database is accessible","jobs_count":42},"storage":{"status":"ok","free_gb":128.5,"used_gb":15.2,"total_gb":143.7,"percent_used":10.6},"gpu":{"available":true,"device_count":1,"devices":[{"name":"NVIDIA GeForce RTX 3080","memory_total_gb":10.0,"memory_free_gb":8.5}]},"registry":{"status":"ok","pipelines_loaded":4,"pipeline_names":["face","person","audio","scene"]}}}}}}}},"503":{"description":"Service unhealthy (detailed mode only)","content":{"application/json":{"example":{"status":"unhealthy","version":"1.3.0","timestamp":"2025-10-22T12:00:00.000Z","details":{"database":{"status":"error","error":"Connection timeout after 5s"},"storage":{"status":"ok"},"gpu":{"available":true},"registry":{"status":"ok"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/":{"post":{"tags":["jobs"],"summary":"Submit Video Processing Job","description":"Submit a video file for processing with one or more annotation pipelines.\n\nThe video is uploaded as multipart/form-data and processed asynchronously.\nReturns immediately with a job ID that can be used to check status and retrieve results.\n\n**Configuration Validation**: If both config and selected_pipelines are provided,\nthe configuration is validated against each pipeline's requirements before job creation.\n\n**Supported Video Formats**: MP4, AVI, MOV, MKV, WEBM (FFmpeg-compatible formats)\n\n**curl Example - Basic Submission**:\n```bash\ncurl -X POST \"http://localhost:18011/api/v1/jobs/\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -F \"video=@/path/to/video.mp4\"\n```\n\n**curl Example - With Pipeline Selection**:\n```bash\ncurl -X POST \"http://localhost:18011/api/v1/jobs/\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -F \"video=@/path/to/video.mp4\" \\\n -F \"selected_pipelines=person_tracking,face_recognition\"\n```\n\n**curl Example - With Configuration**:\n```bash\ncurl -X POST \"http://localhost:18011/api/v1/jobs/\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -F \"video=@/path/to/video.mp4\" \\\n -F \"selected_pipelines=person_tracking\" \\\n -F 'config={\"person_tracking\":{\"confidence_threshold\":0.7}}'\n```\n\n**Success Response** (201 Created):\n```json\n{\n \"id\": \"abc123-def456-ghi789\",\n \"status\": \"pending\",\n \"video_path\": \"/tmp/uploads/video.mp4\",\n \"config\": {\"person_tracking\": {\"confidence_threshold\": 0.7}},\n \"selected_pipelines\": [\"person_tracking\"],\n \"created_at\": \"2025-10-22T10:30:00Z\",\n \"completed_at\": null,\n \"error_message\": null,\n \"result_path\": null,\n \"storage_path\": \"/storage/jobs/abc123-def456-ghi789\"\n}\n```\n\n**Error Response** (400 Bad Request - Invalid Configuration):\n```json\n{\n \"error\": {\n \"code\": \"INVALID_CONFIG\",\n \"message\": \"Configuration validation failed: person_tracking: Invalid value for confidence_threshold (must be between 0 and 1)\",\n \"hint\": \"Fix the validation errors and resubmit\",\n \"timestamp\": \"2025-10-22T10:30:00Z\"\n }\n}\n```\n\n**Error Response** (401 Unauthorized - Missing/Invalid API Key):\n```json\n{\n \"error\": {\n \"code\": \"UNAUTHORIZED\",\n \"message\": \"Invalid or missing API key\",\n \"hint\": \"Include valid API key in Authorization header: Bearer YOUR_KEY\",\n \"timestamp\": \"2025-10-22T10:30:00Z\"\n }\n}\n```","operationId":"submit_job_api_v1_jobs__post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_submit_job_api_v1_jobs__post"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["jobs"],"summary":"List Processing Jobs","description":"List all video processing jobs with pagination and optional status filtering.\n\nReturns a paginated list of jobs with their current status, configuration, and metadata.\nUse this endpoint to monitor multiple jobs or filter by status.\n\n**Status Values**: pending, running, completed, failed, cancelled\n\n**curl Example - List All Jobs**:\n```bash\ncurl -X GET \"http://localhost:18011/api/v1/jobs/\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n**curl Example - Filter by Status**:\n```bash\ncurl -X GET \"http://localhost:18011/api/v1/jobs/?status_filter=completed\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n**curl Example - Pagination**:\n```bash\ncurl -X GET \"http://localhost:18011/api/v1/jobs/?page=2&per_page=20\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n**Success Response** (200 OK):\n```json\n{\n \"jobs\": [\n {\n \"id\": \"abc123-def456\",\n \"status\": \"completed\",\n \"video_path\": \"/tmp/uploads/video1.mp4\",\n \"config\": {\"person_tracking\": {\"confidence_threshold\": 0.7}},\n \"selected_pipelines\": [\"person_tracking\"],\n \"created_at\": \"2025-10-22T10:00:00Z\",\n \"completed_at\": \"2025-10-22T10:05:23Z\",\n \"error_message\": null,\n \"result_path\": \"/storage/jobs/abc123-def456/results\",\n \"storage_path\": \"/storage/jobs/abc123-def456\"\n },\n {\n \"id\": \"xyz789-uvw012\",\n \"status\": \"running\",\n \"video_path\": \"/tmp/uploads/video2.mp4\",\n \"config\": null,\n \"selected_pipelines\": [\"face_recognition\"],\n \"created_at\": \"2025-10-22T10:10:00Z\",\n \"completed_at\": null,\n \"error_message\": null,\n \"result_path\": null,\n \"storage_path\": \"/storage/jobs/xyz789-uvw012\"\n }\n ],\n \"total\": 2,\n \"page\": 1,\n \"per_page\": 10\n}\n```\n\n**Error Response** (401 Unauthorized):\n```json\n{\n \"error\": {\n \"code\": \"UNAUTHORIZED\",\n \"message\": \"Invalid or missing API key\",\n \"hint\": \"Include valid API key in Authorization header\",\n \"timestamp\": \"2025-10-22T10:30:00Z\"\n }\n}\n```","operationId":"list_jobs_api_v1_jobs__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Page"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","default":10,"title":"Per Page"}},{"name":"status_filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Filter"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}":{"get":{"tags":["jobs"],"summary":"Get Job Status","description":"Retrieve the current status and details of a specific video processing job.\n\nUse this endpoint to poll job status during processing. The status field indicates\nthe current state of the job: pending, running, completed, failed, or cancelled.\n\n**Status Values**:\n- `pending`: Job queued, not yet started\n- `running`: Job currently processing\n- `completed`: Job finished successfully, results available\n- `failed`: Job encountered an error (see error_message)\n- `cancelled`: Job was cancelled by user request\n\n**curl Example**:\n```bash\ncurl -X GET \"http://localhost:18011/api/v1/jobs/abc123-def456\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n**Success Response** (200 OK - Running Job):\n```json\n{\n \"id\": \"abc123-def456\",\n \"status\": \"running\",\n \"video_path\": \"/tmp/uploads/video.mp4\",\n \"config\": {\"person_tracking\": {\"confidence_threshold\": 0.7}},\n \"selected_pipelines\": [\"person_tracking\", \"face_recognition\"],\n \"created_at\": \"2025-10-22T10:00:00Z\",\n \"completed_at\": null,\n \"error_message\": null,\n \"result_path\": null,\n \"storage_path\": \"/storage/jobs/abc123-def456\"\n}\n```\n\n**Success Response** (200 OK - Completed Job):\n```json\n{\n \"id\": \"abc123-def456\",\n \"status\": \"completed\",\n \"video_path\": \"/tmp/uploads/video.mp4\",\n \"config\": {\"person_tracking\": {\"confidence_threshold\": 0.7}},\n \"selected_pipelines\": [\"person_tracking\"],\n \"created_at\": \"2025-10-22T10:00:00Z\",\n \"completed_at\": \"2025-10-22T10:05:23Z\",\n \"error_message\": null,\n \"result_path\": \"/storage/jobs/abc123-def456/results\",\n \"storage_path\": \"/storage/jobs/abc123-def456\"\n}\n```\n\n**Error Response** (404 Not Found):\n```json\n{\n \"error\": {\n \"code\": \"JOB_NOT_FOUND\",\n \"message\": \"Job abc123-invalid not found\",\n \"detail\": {\"job_id\": \"abc123-invalid\"},\n \"hint\": \"Check job ID or use GET /api/v1/jobs to list all jobs\",\n \"timestamp\": \"2025-10-22T10:30:00Z\"\n }\n}\n```\n\n**Error Response** (401 Unauthorized):\n```json\n{\n \"error\": {\n \"code\": \"UNAUTHORIZED\",\n \"message\": \"Invalid or missing API key\",\n \"hint\": \"Include valid API key in Authorization header\",\n \"timestamp\": \"2025-10-22T10:30:00Z\"\n }\n}\n```","operationId":"get_job_status_api_v1_jobs__job_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["jobs"],"summary":"Cancel Job","description":"Cancel/delete a job.\n\nArgs:\n job_id: Job ID to cancel","operationId":"cancel_job_api_v1_jobs__job_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}/cancel":{"post":{"tags":["jobs"],"summary":"Cancel Job","description":"Cancel a running or pending video processing job.\n\nAttempts to gracefully stop job execution. Jobs that are already completed, failed,\nor previously cancelled return their current status (idempotent operation).\n\n**Cancellation Behavior**:\n- `pending` jobs: Removed from queue, never started\n- `running` jobs: Interrupted, partial results may be available\n- `completed/failed` jobs: Cannot be cancelled (returns 409 error)\n- `cancelled` jobs: Returns current state (idempotent)\n\n**curl Example**:\n```bash\ncurl -X POST \"http://localhost:18011/api/v1/jobs/abc123-def456/cancel\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n**Success Response** (200 OK - Job Cancelled):\n```json\n{\n \"id\": \"abc123-def456\",\n \"status\": \"cancelled\",\n \"video_path\": \"/tmp/uploads/video.mp4\",\n \"config\": {\"person_tracking\": {\"confidence_threshold\": 0.7}},\n \"selected_pipelines\": [\"person_tracking\"],\n \"created_at\": \"2025-10-22T10:00:00Z\",\n \"completed_at\": \"2025-10-22T10:02:15Z\",\n \"error_message\": \"Job cancelled by user request\",\n \"result_path\": null,\n \"storage_path\": \"/storage/jobs/abc123-def456\"\n}\n```\n\n**Error Response** (404 Not Found):\n```json\n{\n \"error\": {\n \"code\": \"JOB_NOT_FOUND\",\n \"message\": \"Job abc123-invalid not found\",\n \"detail\": {\"job_id\": \"abc123-invalid\"},\n \"hint\": \"Check job ID or use GET /api/v1/jobs to list all jobs\",\n \"timestamp\": \"2025-10-22T10:30:00Z\"\n }\n}\n```\n\n**Error Response** (409 Conflict - Already Completed):\n```json\n{\n \"error\": {\n \"code\": \"JOB_ALREADY_COMPLETED\",\n \"message\": \"Job abc123-def456 is already completed (status: completed)\",\n \"detail\": {\"job_id\": \"abc123-def456\", \"status\": \"completed\"},\n \"hint\": \"Cannot cancel a job that has already finished\",\n \"timestamp\": \"2025-10-22T10:30:00Z\"\n }\n}\n```","operationId":"cancel_job_endpoint_api_v1_jobs__job_id__cancel_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}/results":{"get":{"tags":["jobs"],"summary":"Get Job Results","description":"Retrieve detailed results for a completed video processing job.\n\nReturns pipeline-specific outputs, annotation counts, processing times, and download URLs\nfor generated files. Only available after job completes successfully.\n\n**Result Files**: Each pipeline generates output files (e.g., person_tracking.json,\nface_recognition.json) that can be downloaded using the provided download_url.\n\n**curl Example**:\n```bash\ncurl -X GET \"http://localhost:18011/api/v1/jobs/abc123-def456/results\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n**Success Response** (200 OK):\n```json\n{\n \"job_id\": \"abc123-def456\",\n \"status\": \"completed\",\n \"pipeline_results\": {\n \"person_tracking\": {\n \"pipeline_name\": \"person_tracking\",\n \"status\": \"completed\",\n \"start_time\": \"2025-10-22T10:00:05Z\",\n \"end_time\": \"2025-10-22T10:03:12Z\",\n \"processing_time\": 187.3,\n \"annotation_count\": 1245,\n \"output_file\": \"/storage/jobs/abc123-def456/person_tracking.json\",\n \"download_url\": \"/api/v1/jobs/abc123-def456/results/files/person_tracking\",\n \"error_message\": null\n },\n \"face_recognition\": {\n \"pipeline_name\": \"face_recognition\",\n \"status\": \"completed\",\n \"start_time\": \"2025-10-22T10:03:15Z\",\n \"end_time\": \"2025-10-22T10:05:23Z\",\n \"processing_time\": 128.1,\n \"annotation_count\": 423,\n \"output_file\": \"/storage/jobs/abc123-def456/face_recognition.json\",\n \"download_url\": \"/api/v1/jobs/abc123-def456/results/files/face_recognition\",\n \"error_message\": null\n }\n },\n \"created_at\": \"2025-10-22T10:00:00Z\",\n \"completed_at\": \"2025-10-22T10:05:23Z\",\n \"result_path\": \"/storage/jobs/abc123-def456/results\"\n}\n```\n\n**Error Response** (404 Not Found):\n```json\n{\n \"error\": {\n \"code\": \"JOB_NOT_FOUND\",\n \"message\": \"Job abc123-invalid not found\",\n \"detail\": {\"job_id\": \"abc123-invalid\"},\n \"hint\": \"Check job ID or use GET /api/v1/jobs to list all jobs\",\n \"timestamp\": \"2025-10-22T10:30:00Z\"\n }\n}\n```\n\n**Note**: For jobs still in progress, use GET /jobs/{job_id} to check status first.","operationId":"get_job_results_api_v1_jobs__job_id__results_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResultsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}/results/files/{pipeline_name}":{"get":{"tags":["jobs"],"summary":"Download Result File","description":"Download a specific result file from a job.\n\nArgs:\n job_id: Job ID\n pipeline_name: Name of pipeline to download results for\n\nReturns:\n File download response","operationId":"download_result_file_api_v1_jobs__job_id__results_files__pipeline_name__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"pipeline_name","in":"path","required":true,"schema":{"type":"string","title":"Pipeline Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Download Result File Api V1 Jobs Job Id Results Files Pipeline Name Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/pipelines/":{"get":{"tags":["pipelines"],"summary":"List all available video annotation pipelines","description":"Retrieves a comprehensive list of all registered pipelines available for video annotation,\nincluding their metadata, configuration schemas, capabilities, and supported tasks.\n\nEach pipeline includes:\n- Basic metadata (name, display_name, description, family, variant)\n- Task taxonomy (tasks, modalities, capabilities)\n- Backend requirements and stability level\n- Output formats and types\n- Configuration schema with parameter types and defaults\n- Usage examples\n\n**Example Request:**\n```bash\ncurl -X GET \"http://localhost:18011/api/v1/pipelines\" \\\n -H \"X-API-Key: your-api-key-here\"\n```\n\n**Success Response (200 OK):**\n```json\n{\n \"pipelines\": [\n {\n \"name\": \"openface3_identity\",\n \"display_name\": \"OpenFace 3 - Identity\",\n \"description\": \"Face detection, tracking, and identity recognition\",\n \"pipeline_family\": \"openface\",\n \"variant\": \"identity\",\n \"tasks\": [\"face_detection\", \"face_tracking\", \"face_recognition\"],\n \"modalities\": [\"video\"],\n \"capabilities\": [\"detection\", \"tracking\", \"recognition\"],\n \"backends\": [\"openface\"],\n \"stability\": \"stable\",\n \"outputs\": [\n {\n \"format\": \"COCO\",\n \"types\": [\"detection\", \"tracking\", \"recognition\"]\n }\n ],\n \"config_schema\": {\n \"detection_confidence\": {\n \"type\": \"float\",\n \"default\": 0.5,\n \"description\": \"Minimum confidence threshold for face detection\"\n }\n },\n \"examples\": [\n \"videoannotator job submit --video input.mp4 --pipeline openface3_identity\"\n ]\n }\n ],\n \"total\": 1\n}\n```\n\n**Error Response (401 Unauthorized):**\n```json\n{\n \"error\": {\n \"code\": \"UNAUTHORIZED\",\n \"message\": \"Invalid or missing API key\"\n }\n}\n```\n\nThe pipeline list is dynamically loaded from the registry metadata, ensuring all\nregistered pipelines are discoverable. Use this endpoint to explore available\npipelines before submitting jobs.","operationId":"list_pipelines_api_v1_pipelines__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineListResponse"}}}}}}},"/api/v1/pipelines/{pipeline_name}":{"get":{"tags":["pipelines"],"summary":"Get detailed information about a specific pipeline","description":"Retrieves comprehensive metadata and configuration details for a single pipeline\nspecified by name. Use this endpoint to explore pipeline capabilities, configuration\noptions, and usage examples before submitting jobs.\n\n**Pipeline Information Includes:**\n- Taxonomy: tasks, modalities, capabilities\n- Backend requirements and stability level\n- Output formats and annotation types\n- Complete configuration schema with types, defaults, and descriptions\n- Usage examples (CLI and API)\n\n**Example Request:**\n```bash\ncurl -X GET \"http://localhost:18011/api/v1/pipelines/openface3_identity\" \\\n -H \"X-API-Key: your-api-key-here\"\n```\n\n**Success Response (200 OK):**\n```json\n{\n \"name\": \"openface3_identity\",\n \"display_name\": \"OpenFace 3 - Identity\",\n \"description\": \"Face detection, tracking, and identity recognition using OpenFace 3\",\n \"pipeline_family\": \"openface\",\n \"variant\": \"identity\",\n \"tasks\": [\"face_detection\", \"face_tracking\", \"face_recognition\"],\n \"modalities\": [\"video\"],\n \"capabilities\": [\"detection\", \"tracking\", \"recognition\"],\n \"backends\": [\"openface\"],\n \"stability\": \"stable\",\n \"outputs\": [\n {\n \"format\": \"COCO\",\n \"types\": [\"detection\", \"tracking\", \"recognition\"]\n }\n ],\n \"config_schema\": {\n \"detection_confidence\": {\n \"type\": \"float\",\n \"default\": 0.5,\n \"description\": \"Minimum confidence threshold for face detection (0.0-1.0)\"\n },\n \"enable_landmarks\": {\n \"type\": \"bool\",\n \"default\": true,\n \"description\": \"Extract facial landmarks for alignment\"\n }\n },\n \"examples\": [\n \"videoannotator job submit --video input.mp4 --pipeline openface3_identity\",\n \"videoannotator job submit --video input.mp4 --pipeline openface3_identity --config detection_confidence=0.7\"\n ]\n}\n```\n\n**Error Response (404 Not Found):**\n```json\n{\n \"error\": {\n \"code\": \"PIPELINE_NOT_FOUND\",\n \"message\": \"Pipeline 'invalid_name' not found\",\n \"hint\": \"Run 'videoannotator pipelines --detailed' to list available pipelines\"\n }\n}\n```\n\n**Error Response (401 Unauthorized):**\n```json\n{\n \"error\": {\n \"code\": \"UNAUTHORIZED\",\n \"message\": \"Invalid or missing API key\"\n }\n}\n```\n\nUse the configuration schema to validate parameters before job submission.\nAll configuration parameters are optional and have sensible defaults.","operationId":"get_pipeline_info_api_v1_pipelines__pipeline_name__get","parameters":[{"name":"pipeline_name","in":"path","required":true,"schema":{"type":"string","description":"The unique identifier/name of the pipeline (e.g., 'openface3_identity', 'whisper_transcription')","title":"Pipeline Name"},"description":"The unique identifier/name of the pipeline (e.g., 'openface3_identity', 'whisper_transcription')","example":"openface3_identity"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineInfo"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/pipelines/{pipeline_name}/validate":{"post":{"tags":["pipelines"],"summary":"Validate Pipeline Config","description":"Validate a pipeline configuration.\n\nArgs:\n pipeline_name: Name of the pipeline\n request: Configuration validation request\n\nReturns:\n Validation result with errors and warnings","operationId":"validate_pipeline_config_api_v1_pipelines__pipeline_name__validate_post","parameters":[{"name":"pipeline_name","in":"path","required":true,"schema":{"type":"string","title":"Pipeline Name"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/videoannotator__api__v1__pipelines__ConfigValidationRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/videoannotator__api__v1__pipelines__ConfigValidationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/config/validate":{"post":{"tags":["config"],"summary":"Validate Config","description":"Validate a complete job configuration against selected pipelines.\n\nThis endpoint validates configuration for multiple pipelines at once,\nproviding comprehensive error and warning reporting.\n\nArgs:\n request: Configuration validation request with config and pipeline list\n\nReturns:\n Validation result with errors, warnings, and helpful messages\n\nExample:\n ```json\n POST /api/v1/config/validate\n {\n \"config\": {\n \"person_tracking\": {\"confidence_threshold\": 0.5},\n \"audio_processing\": {\"sample_rate\": 16000}\n },\n \"selected_pipelines\": [\"person_tracking\", \"whisper_transcription\"]\n }\n ```","operationId":"validate_config_api_v1_config_validate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/videoannotator__api__v1__config__ConfigValidationRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/videoannotator__api__v1__config__ConfigValidationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/health":{"get":{"tags":["system"],"summary":"Comprehensive system health and resource monitoring","description":"Returns detailed system health information including CPU, memory, disk usage,\nGPU availability, database status, pipeline registry, and service health.\n\nThis endpoint provides comprehensive diagnostics useful for:\n- Monitoring system resource usage\n- Verifying GPU availability for ML pipelines\n- Checking pipeline registry status\n- Validating database connectivity\n- Assessing overall system capacity\n\n**Example Request:**\n```bash\ncurl -X GET \"http://localhost:18011/api/v1/system/health\" \\\n -H \"X-API-Key: your-api-key-here\"\n```\n\n**Success Response (200 OK):**\n```json\n{\n \"status\": \"healthy\",\n \"timestamp\": \"2025-01-08T10:30:45.123456\",\n \"api_version\": \"1.2.0\",\n \"videoannotator_version\": \"1.2.0\",\n \"system\": {\n \"platform\": \"Linux-6.5.0-1025-azure-x86_64-with-glibc2.35\",\n \"python_version\": \"3.10.12\",\n \"cpu_count\": 8,\n \"cpu_percent\": 15.3,\n \"memory_percent\": 42.5,\n \"memory\": {\n \"total\": 16777216000,\n \"available\": 9663676416,\n \"percent\": 42.5,\n \"used\": 7113539584,\n \"free\": 9663676416\n },\n \"disk\": {\n \"total\": 107374182400,\n \"used\": 45097156608,\n \"free\": 62277025792,\n \"percent\": 42.0\n }\n },\n \"database\": {\n \"status\": \"healthy\",\n \"message\": \"Database is accessible\",\n \"writable\": true\n },\n \"gpu\": {\n \"available\": true,\n \"device_count\": 1,\n \"current_device\": 0,\n \"device_name\": \"NVIDIA GeForce RTX 3090\",\n \"compute_capability\": \"8.6\",\n \"memory_allocated\": 512000000,\n \"memory_reserved\": 1024000000\n },\n \"pipelines\": {\n \"total\": 12,\n \"names\": [\n \"openface3_identity\",\n \"whisper_transcription\",\n \"diarization_pyannote\"\n ]\n },\n \"workers\": {\n \"status\": \"running\",\n \"active_jobs\": 2,\n \"processing_jobs\": [\"job-123\", \"job-456\"],\n \"queued_jobs\": 3,\n \"max_concurrent_workers\": 2,\n \"poll_interval_seconds\": 5\n },\n \"services\": {\n \"database\": {\n \"status\": \"healthy\",\n \"message\": \"Database is accessible\"\n },\n \"job_queue\": \"embedded\",\n \"pipelines\": \"ready\"\n },\n \"security\": {\n \"auth_required\": true\n },\n \"uptime_seconds\": 3672\n}\n```\n\n**Unhealthy Response (200 OK with status unhealthy):**\n```json\n{\n \"status\": \"unhealthy\",\n \"timestamp\": \"2025-01-08T10:30:45.123456\",\n \"error\": \"Failed to connect to database\",\n \"api_version\": \"1.2.0\",\n \"videoannotator_version\": \"1.2.0\"\n}\n```\n\n**GPU Not Available Response:**\n```json\n{\n \"gpu\": {\n \"available\": false,\n \"reason\": \"CUDA not available\"\n }\n}\n```\n\n**GPU Compatibility Warning (old GPU detected):**\n```json\n{\n \"gpu\": {\n \"available\": true,\n \"device_name\": \"NVIDIA GeForce GTX 1060 6GB\",\n \"compute_capability\": \"6.1\",\n \"compatibility_warning\": \"GPU compute capability 6.1 is below PyTorch 2.5.0 minimum requirement (7.0). GPU acceleration may not work. Consider downgrading PyTorch to 1.13.x for older GPUs or upgrading hardware.\",\n \"pytorch_version\": \"2.5.0\",\n \"min_compute_capability\": 7.0\n }\n}\n```\n\n**Worker Information:**\n\nThe `workers` section provides real-time information about the background job processing:\n- `status`: Whether the worker is \"running\" or \"stopped\"\n- `active_jobs`: Number of jobs currently being processed\n- `processing_jobs`: List of job IDs currently being processed\n- `queued_jobs`: Number of jobs waiting in the queue (pending status)\n- `max_concurrent_workers`: Maximum number of jobs that can run simultaneously\n- `poll_interval_seconds`: How often the worker checks for new jobs\n\nThis information is useful for monitoring system load and capacity planning.\n\n**Note**: This endpoint is more resource-intensive than the basic `/health` endpoint\ndue to system metrics collection (CPU sampling, disk I/O). For lightweight health\nchecks, use the root `/health` endpoint instead.\n\nThe `uptime_seconds` field shows how long the API server has been running,\nuseful for monitoring restarts and stability.\n\nThe `gpu.compute_capability` field indicates the CUDA compute capability of the GPU,\nwhich determines compatibility with PyTorch versions. Modern PyTorch (2.5+) requires\ncompute capability 7.0 or higher (Volta architecture). If your GPU is older, a\n`compatibility_warning` will be included with recommended actions.","operationId":"detailed_health_check_api_v1_system_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/system/metrics":{"get":{"tags":["system"],"summary":"Get System Metrics","description":"Get system performance metrics.\n\nReturns:\n System performance and usage metrics","operationId":"get_system_metrics_api_v1_system_metrics_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/system/config":{"get":{"tags":["system"],"summary":"Get System Config","description":"Get current system configuration.\n\nReturns:\n System configuration information (non-sensitive)","operationId":"get_system_config_api_v1_system_config_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/system/database":{"get":{"tags":["system"],"summary":"Get Database Info Endpoint","description":"Get database information and statistics.\n\nReturns:\n Database configuration and statistics","operationId":"get_database_info_endpoint_api_v1_system_database_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/debug/server-info":{"get":{"tags":["debug"],"summary":"Get Server Debug Info","description":"Get comprehensive server information for debugging.\n\nReturns server configuration, status, and system information.","operationId":"get_server_debug_info_api_v1_debug_server_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/debug/token-info":{"get":{"tags":["debug"],"summary":"Get Token Debug Info","description":"Get detailed information about the current API token.\n\nReturns token validation status, permissions, and rate limiting\ninfo.","operationId":"get_token_debug_info_api_v1_debug_token_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Token Debug Info Api V1 Debug Token Info Get"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/debug/pipelines":{"get":{"tags":["debug"],"summary":"Get Pipeline Debug Info","description":"Get detailed pipeline configuration and status information.\n\nReturns comprehensive pipeline information including components,\nparameters, and current status.","operationId":"get_pipeline_debug_info_api_v1_debug_pipelines_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/debug/jobs/{job_id}":{"get":{"tags":["debug"],"summary":"Get Job Debug Info","description":"Get detailed debugging information for a specific job.\n\nReturns comprehensive job status, logs, resource usage, and file\ninformation.","operationId":"get_job_debug_info_api_v1_debug_jobs__job_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Job Debug Info Api V1 Debug Jobs Job Id Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/debug/request-log":{"get":{"tags":["debug"],"summary":"Get Request Log","description":"Get recent API request log for debugging.\n\nReturns recent API requests with timing and status information.","operationId":"get_request_log_api_v1_debug_request_log_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of requests to return","default":50,"title":"Limit"},"description":"Maximum number of requests to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Request Log Api V1 Debug Request Log Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/debug/mock-events":{"get":{"tags":["debug"],"summary":"Mock Sse Events","description":"Mock SSE endpoint for client testing until real SSE is implemented.\n\nReturns Server-Sent Events format for job monitoring testing.","operationId":"mock_sse_events_api_v1_debug_mock_events_get","parameters":[{"name":"token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API token for authentication","title":"Token"},"description":"API token for authentication"},{"name":"job_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Job ID to monitor","title":"Job Id"},"description":"Job ID to monitor"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Mock Sse Events Api V1 Debug Mock Events Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/debug/background-jobs":{"get":{"tags":["debug"],"summary":"Get Background Jobs Status","description":"Get status of background job processing system.\n\nReturns information about the background job manager including\ncurrently processing jobs and system status.","operationId":"get_background_jobs_status_api_v1_debug_background_jobs_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Background Jobs Status Api V1 Debug Background Jobs Get"}}}}}}},"/api/v1/events/stream":{"get":{"tags":["events"],"summary":"Events Stream","description":"Server-Sent Events endpoint for real-time updates.\n\n This endpoint provides a basic SSE implementation for client compatibility.\n Enhanced real-time job status updates will be added in v1.3.0.\n\nReturns:\n StreamingResponse: SSE stream with periodic heartbeat events","operationId":"events_stream_api_v1_events_stream_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"summary":"Health Check","description":"Return basic health status information.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"Body_submit_job_api_v1_jobs__post":{"properties":{"video":{"type":"string","format":"binary","title":"Video","description":"Video file to process (MP4, AVI, MOV, MKV, WEBM)"},"config":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Config","description":"JSON configuration object for pipeline parameters. Example: '{\"person_tracking\":{\"confidence_threshold\":0.7}}'"},"selected_pipelines":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Pipelines","description":"Comma-separated list of pipeline names to run. Example: 'person_tracking,face_recognition'. Use GET /api/v1/pipelines to list available pipelines."}},"type":"object","required":["video"],"title":"Body_submit_job_api_v1_jobs__post"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"JobListResponse":{"properties":{"jobs":{"items":{"$ref":"#/components/schemas/JobResponse"},"type":"array","title":"Jobs"},"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"per_page":{"type":"integer","title":"Per Page"}},"type":"object","required":["jobs","total","page","per_page"],"title":"JobListResponse","description":"Response model for job listing."},"JobResponse":{"properties":{"id":{"type":"string","title":"Id"},"status":{"type":"string","title":"Status"},"video_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Video Path"},"video_filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Video Filename","description":"Original video filename"},"video_size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Video Size Bytes","description":"Video file size in bytes"},"video_duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Video Duration Seconds","description":"Video duration in seconds"},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config"},"selected_pipelines":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Selected Pipelines"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"result_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Path"},"storage_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Storage Path"}},"type":"object","required":["id","status"],"title":"JobResponse","description":"Response model for job information (aligned with DB Job model)."},"JobResultsResponse":{"properties":{"job_id":{"type":"string","title":"Job Id"},"status":{"type":"string","title":"Status"},"pipeline_results":{"additionalProperties":{"$ref":"#/components/schemas/PipelineResultResponse"},"type":"object","title":"Pipeline Results"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"result_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Path"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"}},"type":"object","required":["job_id","status","pipeline_results"],"title":"JobResultsResponse","description":"Response model for job results (aligned with DB schema)."},"PipelineInfo":{"properties":{"name":{"type":"string","title":"Name"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"description":{"type":"string","title":"Description"},"enabled":{"type":"boolean","title":"Enabled","default":true},"pipeline_family":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pipeline Family"},"variant":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant"},"tasks":{"items":{"type":"string"},"type":"array","title":"Tasks","default":[]},"modalities":{"items":{"type":"string"},"type":"array","title":"Modalities","default":[]},"capabilities":{"items":{"type":"string"},"type":"array","title":"Capabilities","default":[]},"backends":{"items":{"type":"string"},"type":"array","title":"Backends","default":[]},"stability":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stability"},"outputs":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Outputs"},"config_schema":{"additionalProperties":true,"type":"object","title":"Config Schema"},"examples":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Examples","default":[]}},"type":"object","required":["name","description","outputs","config_schema"],"title":"PipelineInfo","description":"Information about an available pipeline (extended taxonomy)."},"PipelineListResponse":{"properties":{"pipelines":{"items":{"$ref":"#/components/schemas/PipelineInfo"},"type":"array","title":"Pipelines"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["pipelines","total"],"title":"PipelineListResponse","description":"Response for pipeline listing."},"PipelineResultResponse":{"properties":{"pipeline_name":{"type":"string","title":"Pipeline Name"},"status":{"type":"string","title":"Status"},"start_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Time"},"end_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Time"},"processing_time":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Processing Time"},"annotation_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Annotation Count"},"output_file":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output File"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"}},"type":"object","required":["pipeline_name","status"],"title":"PipelineResultResponse","description":"Response model for individual pipeline results."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"videoannotator__api__v1__config__ConfigValidationRequest":{"properties":{"config":{"additionalProperties":true,"type":"object","title":"Config"},"selected_pipelines":{"items":{"type":"string"},"type":"array","title":"Selected Pipelines"}},"type":"object","required":["config","selected_pipelines"],"title":"ConfigValidationRequest","description":"Request for full configuration validation."},"videoannotator__api__v1__config__ConfigValidationResponse":{"properties":{"valid":{"type":"boolean","title":"Valid"},"errors":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Errors"},"warnings":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Warnings"},"message":{"type":"string","title":"Message"},"pipelines_validated":{"items":{"type":"string"},"type":"array","title":"Pipelines Validated"}},"type":"object","required":["valid","errors","warnings","message","pipelines_validated"],"title":"ConfigValidationResponse","description":"Response for config validation."},"videoannotator__api__v1__pipelines__ConfigValidationRequest":{"properties":{"config":{"additionalProperties":true,"type":"object","title":"Config"},"selected_pipelines":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Selected Pipelines"}},"type":"object","required":["config"],"title":"ConfigValidationRequest","description":"Request for config validation."},"videoannotator__api__v1__pipelines__ConfigValidationResponse":{"properties":{"valid":{"type":"boolean","title":"Valid"},"errors":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Errors"},"warnings":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Warnings"},"message":{"type":"string","title":"Message"}},"type":"object","required":["valid","errors","warnings","message"],"title":"ConfigValidationResponse","description":"Response for config validation."}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}}}