{ "openapi": "3.1.0", "info": { "title": "ImageExtract API", "version": "v1", "description": "Developer-first image extraction API for creating jobs, checking status, reading results, and downloading extracted images or exports." }, "servers": [ { "url": "https://imageextract.com" } ], "security": [], "tags": [ { "name": "Jobs", "description": "Extraction jobs, results, downloads, and exports." } ], "components": { "securitySchemes": { "browserSession": { "type": "apiKey", "in": "cookie", "name": "sb--auth-token", "description": "Supabase browser session cookie. Used by same-origin dashboard requests." }, "projectApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ImageExtract project API key", "description": "Project API key in the form `ie_live_...`." } } }, "paths": { "/api/v1/jobs": { "post": { "tags": [ "Jobs" ], "summary": "Create extraction job", "description": "Creates a URL, bulk, or document extraction job. JSON requests support URL and bulk jobs. Multipart form-data supports document uploads.", "operationId": "jobs-create", "deprecated": false, "security": [ { "browserSession": [] }, { "projectApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key for safe client retries.", "schema": { "type": "string" }, "example": "6f4a2c0a-72b1-48cb-bf66-4c3f0d46b9e5" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "input": { "type": "string", "format": "uri" } }, "required": [ "type", "input" ], "additionalProperties": false }, "example": { "type": "url", "input": "https://www.python.org/" } } } }, "responses": { "202": { "description": "Job queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" } }, "required": [ "job_id" ], "additionalProperties": false }, "example": { "job_id": "f5ffd46b-9823-4885-89fc-db1dc80b6e17" } } } }, "400": { "description": "Validation error, unsupported document type, or SSRF-blocked URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "Validation error, unsupported document type, or SSRF-blocked URL", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "Authentication required", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "INSUFFICIENT_CREDITS", "message": "Insufficient credits", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } }, "409": { "description": "Idempotency key reused with a different request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency key reused with a different request body", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } }, "429": { "description": "Rate limit exceeded or daily credit cap exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded or daily credit cap exceeded", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } } }, "x-imageextract-credits": "URL: 2 credits per job. Bulk: 2 credits per URL. Native document: 1 credit per document.", "x-imageextract-rate-limit": "Per-user or per-key rate limiting applies by plan tier.", "x-imageextract-idempotency": "Supported with the `Idempotency-Key` header.", "x-imageextract-auth-mode": "session_or_api_key", "x-imageextract-interactive": true } }, "/api/v1/jobs/{id}": { "get": { "tags": [ "Jobs" ], "summary": "Get job status", "description": "Returns current job status, timing, credits used, partial image counts, and group progress for bulk and document jobs.", "operationId": "job-get", "deprecated": false, "security": [ { "browserSession": [] }, { "projectApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job id.", "schema": { "type": "string" }, "example": "f5ffd46b-9823-4885-89fc-db1dc80b6e17" } ], "responses": { "200": { "description": "Job status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "failed_at": { "type": "null" }, "duration_ms": { "type": "integer" }, "error": { "type": "null" }, "credits_used": { "type": "integer" }, "image_count": { "type": "integer" }, "partial": { "type": "boolean" }, "completed_groups": { "type": "integer" }, "total_groups": { "type": "integer" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "label": { "type": "string", "format": "uri" }, "status": { "type": "string" }, "image_count": { "type": "integer" }, "duration_ms": { "type": "integer" } }, "required": [ "id", "kind", "label", "status", "image_count", "duration_ms" ], "additionalProperties": false } }, "source_groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "label": { "type": "string", "format": "uri" }, "status": { "type": "string" }, "image_count": { "type": "integer" }, "duration_ms": { "type": "integer" } }, "required": [ "id", "kind", "label", "status", "image_count", "duration_ms" ], "additionalProperties": false } } }, "required": [ "id", "type", "status", "created_at", "started_at", "completed_at", "failed_at", "duration_ms", "error", "credits_used", "image_count", "partial", "completed_groups", "total_groups", "groups", "source_groups" ], "additionalProperties": false }, "example": { "id": "f5ffd46b-9823-4885-89fc-db1dc80b6e17", "type": "bulk", "status": "done", "created_at": "2026-01-01T00:00:00.000Z", "started_at": "2026-01-01T00:00:01.000Z", "completed_at": "2026-01-01T00:00:04.101Z", "failed_at": null, "duration_ms": 3101, "error": null, "credits_used": 2, "image_count": 24, "partial": false, "completed_groups": 2, "total_groups": 2, "groups": [ { "id": "76d041f1-973f-4e90-af71-437e6d22c420", "kind": "url", "label": "https://www.python.org/", "status": "done", "image_count": 8, "duration_ms": 3101 } ], "source_groups": [ { "id": "76d041f1-973f-4e90-af71-437e6d22c420", "kind": "url", "label": "https://www.python.org/", "status": "done", "image_count": 8, "duration_ms": 3101 } ] } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "NOT_FOUND", "message": "Job not found", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } } }, "x-imageextract-credits": null, "x-imageextract-rate-limit": null, "x-imageextract-idempotency": null, "x-imageextract-auth-mode": "session_or_api_key", "x-imageextract-interactive": true } }, "/api/v1/jobs/{id}/result": { "get": { "tags": [ "Jobs" ], "summary": "Get job result", "description": "Returns the full extraction result for a completed job.", "operationId": "job-result-get", "deprecated": false, "security": [ { "browserSession": [] }, { "projectApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job id.", "schema": { "type": "string" }, "example": "f5ffd46b-9823-4885-89fc-db1dc80b6e17" } ], "responses": { "200": { "description": "Completed extraction result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "image_count": { "type": "integer" }, "asset_count": { "type": "integer" }, "unique_asset_count": { "type": "integer" }, "variant_count": { "type": "integer" }, "credits_used": { "type": "integer" }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "job_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "normalized_url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "format": { "type": "string" }, "mime_type": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "aspect_ratio": { "type": "number" }, "file_size": { "type": "integer" }, "source_url": { "type": "string", "format": "uri" }, "source_kind": { "type": "string" }, "discovery_methods": { "type": "array", "items": { "type": "string" } }, "preview_url": { "type": "string", "format": "uri" }, "download_url": { "type": "null" }, "storage_url": { "type": "null" }, "storage_key": { "type": "null" }, "color_space": { "type": "null" }, "has_alpha": { "type": "boolean" }, "alt_text": { "type": "string" }, "title": { "type": "null" }, "aria_label": { "type": "null" }, "is_lazy_loaded": { "type": "boolean" }, "is_previewable": { "type": "boolean" } }, "required": [ "id", "job_id", "url", "normalized_url", "filename", "format", "mime_type", "width", "height", "aspect_ratio", "file_size", "source_url", "source_kind", "discovery_methods", "preview_url", "download_url", "storage_url", "storage_key", "color_space", "has_alpha", "alt_text", "title", "aria_label", "is_lazy_loaded", "is_previewable" ], "additionalProperties": false } }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "job_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "normalized_url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "format": { "type": "string" }, "mime_type": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "aspect_ratio": { "type": "number" }, "file_size": { "type": "integer" }, "source_url": { "type": "string", "format": "uri" }, "source_kind": { "type": "string" }, "discovery_methods": { "type": "array", "items": { "type": "string" } }, "preview_url": { "type": "string", "format": "uri" }, "download_url": { "type": "null" }, "storage_url": { "type": "null" }, "storage_key": { "type": "null" }, "color_space": { "type": "null" }, "has_alpha": { "type": "boolean" }, "alt_text": { "type": "string" }, "title": { "type": "null" }, "aria_label": { "type": "null" }, "is_lazy_loaded": { "type": "boolean" }, "is_previewable": { "type": "boolean" } }, "required": [ "id", "job_id", "url", "normalized_url", "filename", "format", "mime_type", "width", "height", "aspect_ratio", "file_size", "source_url", "source_kind", "discovery_methods", "preview_url", "download_url", "storage_url", "storage_key", "color_space", "has_alpha", "alt_text", "title", "aria_label", "is_lazy_loaded", "is_previewable" ], "additionalProperties": false } }, "unique_assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uri" }, "representative_asset_id": { "type": "string" }, "variant_count": { "type": "integer" }, "best_width": { "type": "integer" }, "best_height": { "type": "integer" }, "best_file_size": { "type": "integer" }, "confidence": { "type": "integer" }, "grouping_reason": { "type": "string" } }, "required": [ "id", "representative_asset_id", "variant_count", "best_width", "best_height", "best_file_size", "confidence", "grouping_reason" ], "additionalProperties": false } }, "variant_groups": { "type": "array", "items": {} }, "source_groups": { "type": "array", "items": {} }, "diagnostics": { "type": "object", "properties": { "discovered_refs": { "type": "integer" }, "unique_refs": { "type": "integer" }, "processed_images": { "type": "integer" }, "failed_refs": { "type": "integer" }, "skipped_non_image": { "type": "integer" }, "duplicate_refs": { "type": "integer" }, "sources": { "type": "object", "properties": { "html_img": { "type": "integer" } }, "required": [ "html_img" ], "additionalProperties": false } }, "required": [ "discovered_refs", "unique_refs", "processed_images", "failed_refs", "skipped_non_image", "duplicate_refs", "sources" ], "additionalProperties": false }, "extracted_at": { "type": "string", "format": "date-time" } }, "required": [ "job_id", "type", "image_count", "asset_count", "unique_asset_count", "variant_count", "credits_used", "images", "assets", "unique_assets", "variant_groups", "source_groups", "diagnostics", "extracted_at" ], "additionalProperties": false }, "example": { "job_id": "f5ffd46b-9823-4885-89fc-db1dc80b6e17", "type": "url", "image_count": 1, "asset_count": 1, "unique_asset_count": 1, "variant_count": 0, "credits_used": 1, "images": [ { "id": "7d9c11448acc1470", "job_id": "f5ffd46b-9823-4885-89fc-db1dc80b6e17", "url": "https://www.python.org/static/img/python-logo.png", "normalized_url": "https://www.python.org/static/img/python-logo.png", "filename": "python-logo.png", "format": "png", "mime_type": "image/png", "width": 580, "height": 164, "aspect_ratio": 3.5366, "file_size": 15770, "source_url": "https://www.python.org/", "source_kind": "web", "discovery_methods": [ "html_img" ], "preview_url": "https://www.python.org/static/img/python-logo.png", "download_url": null, "storage_url": null, "storage_key": null, "color_space": null, "has_alpha": false, "alt_text": "python logo", "title": null, "aria_label": null, "is_lazy_loaded": false, "is_previewable": true } ], "assets": [ { "id": "7d9c11448acc1470", "job_id": "f5ffd46b-9823-4885-89fc-db1dc80b6e17", "url": "https://www.python.org/static/img/python-logo.png", "normalized_url": "https://www.python.org/static/img/python-logo.png", "filename": "python-logo.png", "format": "png", "mime_type": "image/png", "width": 580, "height": 164, "aspect_ratio": 3.5366, "file_size": 15770, "source_url": "https://www.python.org/", "source_kind": "web", "discovery_methods": [ "html_img" ], "preview_url": "https://www.python.org/static/img/python-logo.png", "download_url": null, "storage_url": null, "storage_key": null, "color_space": null, "has_alpha": false, "alt_text": "python logo", "title": null, "aria_label": null, "is_lazy_loaded": false, "is_previewable": true } ], "unique_assets": [ { "id": "https://www.python.org/static/img/python-logo.png", "representative_asset_id": "7d9c11448acc1470", "variant_count": 1, "best_width": 580, "best_height": 164, "best_file_size": 15770, "confidence": 1, "grouping_reason": "single_asset" } ], "variant_groups": [], "source_groups": [], "diagnostics": { "discovered_refs": 1, "unique_refs": 1, "processed_images": 1, "failed_refs": 0, "skipped_non_image": 0, "duplicate_refs": 0, "sources": { "html_img": 1 } }, "extracted_at": "2026-01-01T00:00:04.101Z" } } } }, "202": { "description": "Job still processing. Returns a partial result when one is available.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "status": { "type": "string" }, "image_count": { "type": "integer" }, "asset_count": { "type": "integer" }, "unique_asset_count": { "type": "integer" }, "variant_count": { "type": "integer" }, "credits_used": { "type": "integer" }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "job_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "normalized_url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "format": { "type": "string" }, "mime_type": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "aspect_ratio": { "type": "number" }, "file_size": { "type": "integer" }, "source_url": { "type": "string", "format": "uri" }, "source_kind": { "type": "string" }, "discovery_methods": { "type": "array", "items": { "type": "string" } }, "preview_url": { "type": "string", "format": "uri" }, "download_url": { "type": "null" }, "storage_url": { "type": "null" }, "storage_key": { "type": "null" }, "color_space": { "type": "null" }, "has_alpha": { "type": "boolean" }, "alt_text": { "type": "string" }, "title": { "type": "null" }, "aria_label": { "type": "null" }, "is_lazy_loaded": { "type": "boolean" }, "is_previewable": { "type": "boolean" } }, "required": [ "id", "job_id", "url", "normalized_url", "filename", "format", "mime_type", "width", "height", "aspect_ratio", "file_size", "source_url", "source_kind", "discovery_methods", "preview_url", "download_url", "storage_url", "storage_key", "color_space", "has_alpha", "alt_text", "title", "aria_label", "is_lazy_loaded", "is_previewable" ], "additionalProperties": false } }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "job_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "normalized_url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "format": { "type": "string" }, "mime_type": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "aspect_ratio": { "type": "number" }, "file_size": { "type": "integer" }, "source_url": { "type": "string", "format": "uri" }, "source_kind": { "type": "string" }, "discovery_methods": { "type": "array", "items": { "type": "string" } }, "preview_url": { "type": "string", "format": "uri" }, "download_url": { "type": "null" }, "storage_url": { "type": "null" }, "storage_key": { "type": "null" }, "color_space": { "type": "null" }, "has_alpha": { "type": "boolean" }, "alt_text": { "type": "string" }, "title": { "type": "null" }, "aria_label": { "type": "null" }, "is_lazy_loaded": { "type": "boolean" }, "is_previewable": { "type": "boolean" } }, "required": [ "id", "job_id", "url", "normalized_url", "filename", "format", "mime_type", "width", "height", "aspect_ratio", "file_size", "source_url", "source_kind", "discovery_methods", "preview_url", "download_url", "storage_url", "storage_key", "color_space", "has_alpha", "alt_text", "title", "aria_label", "is_lazy_loaded", "is_previewable" ], "additionalProperties": false } }, "unique_assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uri" }, "representative_asset_id": { "type": "string" }, "variant_count": { "type": "integer" }, "best_width": { "type": "integer" }, "best_height": { "type": "integer" }, "best_file_size": { "type": "integer" }, "confidence": { "type": "integer" }, "grouping_reason": { "type": "string" } }, "required": [ "id", "representative_asset_id", "variant_count", "best_width", "best_height", "best_file_size", "confidence", "grouping_reason" ], "additionalProperties": false } }, "variant_groups": { "type": "array", "items": {} }, "source_groups": { "type": "array", "items": {} }, "diagnostics": { "type": "object", "properties": { "discovered_refs": { "type": "integer" }, "unique_refs": { "type": "integer" }, "processed_images": { "type": "integer" }, "failed_refs": { "type": "integer" }, "skipped_non_image": { "type": "integer" }, "duplicate_refs": { "type": "integer" }, "sources": { "type": "object", "properties": { "html_img": { "type": "integer" } }, "required": [ "html_img" ], "additionalProperties": false } }, "required": [ "discovered_refs", "unique_refs", "processed_images", "failed_refs", "skipped_non_image", "duplicate_refs", "sources" ], "additionalProperties": false }, "partial": { "type": "boolean" }, "completed_groups": { "type": "integer" }, "total_groups": { "type": "integer" }, "extracted_at": { "type": "string", "format": "date-time" } }, "required": [ "job_id", "type", "status", "image_count", "asset_count", "unique_asset_count", "variant_count", "credits_used", "images", "assets", "unique_assets", "variant_groups", "source_groups", "diagnostics", "partial", "completed_groups", "total_groups", "extracted_at" ], "additionalProperties": false }, "example": { "job_id": "f5ffd46b-9823-4885-89fc-db1dc80b6e17", "type": "url", "status": "processing", "image_count": 1, "asset_count": 1, "unique_asset_count": 1, "variant_count": 0, "credits_used": 1, "images": [ { "id": "7d9c11448acc1470", "job_id": "f5ffd46b-9823-4885-89fc-db1dc80b6e17", "url": "https://www.python.org/static/img/python-logo.png", "normalized_url": "https://www.python.org/static/img/python-logo.png", "filename": "python-logo.png", "format": "png", "mime_type": "image/png", "width": 580, "height": 164, "aspect_ratio": 3.5366, "file_size": 15770, "source_url": "https://www.python.org/", "source_kind": "web", "discovery_methods": [ "html_img" ], "preview_url": "https://www.python.org/static/img/python-logo.png", "download_url": null, "storage_url": null, "storage_key": null, "color_space": null, "has_alpha": false, "alt_text": "python logo", "title": null, "aria_label": null, "is_lazy_loaded": false, "is_previewable": true } ], "assets": [ { "id": "7d9c11448acc1470", "job_id": "f5ffd46b-9823-4885-89fc-db1dc80b6e17", "url": "https://www.python.org/static/img/python-logo.png", "normalized_url": "https://www.python.org/static/img/python-logo.png", "filename": "python-logo.png", "format": "png", "mime_type": "image/png", "width": 580, "height": 164, "aspect_ratio": 3.5366, "file_size": 15770, "source_url": "https://www.python.org/", "source_kind": "web", "discovery_methods": [ "html_img" ], "preview_url": "https://www.python.org/static/img/python-logo.png", "download_url": null, "storage_url": null, "storage_key": null, "color_space": null, "has_alpha": false, "alt_text": "python logo", "title": null, "aria_label": null, "is_lazy_loaded": false, "is_previewable": true } ], "unique_assets": [ { "id": "https://www.python.org/static/img/python-logo.png", "representative_asset_id": "7d9c11448acc1470", "variant_count": 1, "best_width": 580, "best_height": 164, "best_file_size": 15770, "confidence": 1, "grouping_reason": "single_asset" } ], "variant_groups": [], "source_groups": [], "diagnostics": { "discovered_refs": 1, "unique_refs": 1, "processed_images": 1, "failed_refs": 0, "skipped_non_image": 0, "duplicate_refs": 0, "sources": { "html_img": 1 } }, "partial": true, "completed_groups": 1, "total_groups": 2, "extracted_at": "2026-01-01T00:00:04.101Z" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "NOT_FOUND", "message": "Job not found", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } }, "422": { "description": "Job failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "JOB_FAILED", "message": "Job failed", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } } }, "x-imageextract-credits": null, "x-imageextract-rate-limit": null, "x-imageextract-idempotency": null, "x-imageextract-auth-mode": "session_or_api_key", "x-imageextract-interactive": true } }, "/api/v1/jobs/{id}/exports": { "post": { "tags": [ "Jobs" ], "summary": "Create export", "description": "Starts an async export for all images, selected image ids, one source group, unique assets, or metadata-only CSV/JSON. Exports are routed through plan-aware queues.", "operationId": "job-export-create", "deprecated": false, "security": [ { "browserSession": [] }, { "projectApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job id.", "schema": { "type": "string" }, "example": "f5ffd46b-9823-4885-89fc-db1dc80b6e17" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_ids": { "type": "array", "items": { "type": "string" } }, "source_group_id": { "type": "string", "format": "uuid" }, "template": { "type": "string" } }, "required": [ "image_ids", "source_group_id", "template" ], "additionalProperties": false }, "example": { "image_ids": [ "7d9c11448acc1470" ], "source_group_id": "76d041f1-973f-4e90-af71-437e6d22c420", "template": "grouped" } } } }, "responses": { "202": { "description": "Export queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "export_id": { "type": "string", "format": "uuid" }, "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "template": { "type": "string" }, "total_count": { "type": "integer" }, "completed_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "zip_size": { "type": "null" }, "expires_at": { "type": "string", "format": "date-time" }, "error": { "type": "null" }, "download_url": { "type": "null" }, "queue": { "type": "object", "properties": { "plan": { "type": "string" }, "name": { "type": "string" }, "position": { "type": "integer" }, "position_label": { "type": "string" }, "estimated_wait_seconds": { "type": "null" } }, "required": [ "plan", "name", "position", "position_label", "estimated_wait_seconds" ], "additionalProperties": false } }, "required": [ "export_id", "job_id", "status", "template", "total_count", "completed_count", "failed_count", "zip_size", "expires_at", "error", "download_url", "queue" ], "additionalProperties": false }, "example": { "export_id": "9af68b0c-d2d4-4871-91ea-62b2a1656328", "job_id": "f5ffd46b-9823-4885-89fc-db1dc80b6e17", "status": "queued", "template": "grouped", "total_count": 500, "completed_count": 0, "failed_count": 0, "zip_size": null, "expires_at": "2026-01-02T00:00:00.000Z", "error": null, "download_url": null, "queue": { "plan": "pro", "name": "exports-pro", "position": 3, "position_label": "#3", "estimated_wait_seconds": null } } } } }, "400": { "description": "Job is not ready or no images match the export request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "Job is not ready or no images match the export request", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "NOT_FOUND", "message": "Job not found", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } } }, "x-imageextract-credits": null, "x-imageextract-rate-limit": null, "x-imageextract-idempotency": null, "x-imageextract-auth-mode": "session_or_api_key", "x-imageextract-interactive": true } }, "/api/v1/jobs/{id}/exports/{exportId}": { "get": { "tags": [ "Jobs" ], "summary": "Get export status", "description": "Polls an export while the worker prepares the requested artifact. Queue position is approximate and omitted unless enabled for the environment.", "operationId": "job-export-get", "deprecated": false, "security": [ { "browserSession": [] }, { "projectApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job id.", "schema": { "type": "string" }, "example": "f5ffd46b-9823-4885-89fc-db1dc80b6e17" }, { "name": "exportId", "in": "path", "required": true, "description": "Export id.", "schema": { "type": "string" }, "example": "9af68b0c-d2d4-4871-91ea-62b2a1656328" } ], "responses": { "200": { "description": "Export status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "export_id": { "type": "string", "format": "uuid" }, "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "template": { "type": "string" }, "total_count": { "type": "integer" }, "completed_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "zip_size": { "type": "null" }, "expires_at": { "type": "string", "format": "date-time" }, "error": { "type": "null" }, "download_url": { "type": "null" }, "queue": { "type": "object", "properties": { "plan": { "type": "string" }, "name": { "type": "string" }, "position": { "type": "integer" }, "position_label": { "type": "string" }, "estimated_wait_seconds": { "type": "null" } }, "required": [ "plan", "name", "position", "position_label", "estimated_wait_seconds" ], "additionalProperties": false } }, "required": [ "export_id", "job_id", "status", "template", "total_count", "completed_count", "failed_count", "zip_size", "expires_at", "error", "download_url", "queue" ], "additionalProperties": false }, "example": { "export_id": "9af68b0c-d2d4-4871-91ea-62b2a1656328", "job_id": "f5ffd46b-9823-4885-89fc-db1dc80b6e17", "status": "processing", "template": "grouped", "total_count": 500, "completed_count": 48, "failed_count": 0, "zip_size": null, "expires_at": "2026-01-02T00:00:00.000Z", "error": null, "download_url": null, "queue": { "plan": "pro", "name": "exports-pro", "position": 3, "position_label": "#3", "estimated_wait_seconds": null } } } } }, "404": { "description": "Export not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "NOT_FOUND", "message": "Export not found", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } } }, "x-imageextract-credits": null, "x-imageextract-rate-limit": null, "x-imageextract-idempotency": null, "x-imageextract-auth-mode": "session_or_api_key", "x-imageextract-interactive": true } }, "/api/v1/jobs/{id}/exports/{exportId}/download": { "get": { "tags": [ "Jobs" ], "summary": "Download prepared export", "description": "Authorizes the request, then redirects to a short-lived signed R2 URL for the prepared ZIP, CSV, or JSON artifact.", "operationId": "job-export-download", "deprecated": false, "security": [ { "browserSession": [] }, { "projectApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job id.", "schema": { "type": "string" }, "example": "f5ffd46b-9823-4885-89fc-db1dc80b6e17" }, { "name": "exportId", "in": "path", "required": true, "description": "Export id.", "schema": { "type": "string" }, "example": "9af68b0c-d2d4-4871-91ea-62b2a1656328" } ], "responses": { "202": { "description": "Export is not ready", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "JOB_NOT_READY", "message": "Export is not ready", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } }, "302": { "description": "Redirect to signed artifact download URL.", "content": { "application/json": { "schema": { "type": "string" }, "example": "" } } }, "404": { "description": "Export not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "NOT_FOUND", "message": "Export not found", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } } }, "x-imageextract-credits": null, "x-imageextract-rate-limit": null, "x-imageextract-idempotency": null, "x-imageextract-auth-mode": "session_or_api_key", "x-imageextract-interactive": false } }, "/api/v1/jobs/{id}/downloads/images/{imageId}": { "get": { "tags": [ "Jobs" ], "summary": "Download one image", "description": "Downloads a single extracted image by image id.", "operationId": "job-download-image-get", "deprecated": false, "security": [ { "browserSession": [] }, { "projectApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job id.", "schema": { "type": "string" }, "example": "f5ffd46b-9823-4885-89fc-db1dc80b6e17" }, { "name": "imageId", "in": "path", "required": true, "description": "Image id from the result set.", "schema": { "type": "string" }, "example": "7d9c11448acc1470" } ], "responses": { "200": { "description": "Image binary.", "content": { "application/octet-stream": { "schema": { "type": "string" }, "example": "" } } }, "202": { "description": "Job not yet complete", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "JOB_NOT_READY", "message": "Job not yet complete", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } }, "404": { "description": "Job or image not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "NOT_FOUND", "message": "Job or image not found", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } } }, "x-imageextract-credits": null, "x-imageextract-rate-limit": null, "x-imageextract-idempotency": null, "x-imageextract-auth-mode": "session_or_api_key", "x-imageextract-interactive": false } }, "/api/v1/jobs/{id}/downloads/zip": { "get": { "tags": [ "Jobs" ], "summary": "Request ZIP export", "description": "Legacy ZIP download helper. ZIP exports are async-only, so this endpoint returns instructions for creating an export job.", "operationId": "job-download-zip-get", "deprecated": false, "security": [ { "browserSession": [] }, { "projectApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job id.", "schema": { "type": "string" }, "example": "f5ffd46b-9823-4885-89fc-db1dc80b6e17" } ], "responses": { "409": { "description": "Use async export creation instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false }, "export_url": { "type": "string" }, "method": { "type": "string" }, "body": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } }, "required": [ "error", "export_url", "method", "body" ], "additionalProperties": false }, "example": { "error": { "code": "BAD_REQUEST", "message": "ZIP exports are prepared asynchronously.", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" }, "export_url": "/api/v1/jobs/f5ffd46b-9823-4885-89fc-db1dc80b6e17/exports", "method": "POST", "body": {} } } } } }, "x-imageextract-credits": null, "x-imageextract-rate-limit": null, "x-imageextract-idempotency": null, "x-imageextract-auth-mode": "session_or_api_key", "x-imageextract-interactive": false } }, "/api/v1/jobs/{id}/cancel": { "post": { "tags": [ "Jobs" ], "summary": "Cancel job", "description": "Cancels a pending or queued job. Completed jobs cannot be cancelled.", "operationId": "job-cancel-post", "deprecated": false, "security": [ { "browserSession": [] }, { "projectApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job id.", "schema": { "type": "string" }, "example": "f5ffd46b-9823-4885-89fc-db1dc80b6e17" } ], "responses": { "200": { "description": "Job cancelled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelled": { "type": "boolean" } }, "required": [ "cancelled" ], "additionalProperties": false }, "example": { "cancelled": true } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "NOT_FOUND", "message": "Job not found", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } }, "409": { "description": "Only pending or queued jobs can be cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "Only pending or queued jobs can be cancelled", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } } }, "x-imageextract-credits": null, "x-imageextract-rate-limit": null, "x-imageextract-idempotency": null, "x-imageextract-auth-mode": "session_or_api_key", "x-imageextract-interactive": true } }, "/api/v1/jobs/{id}/retry": { "post": { "tags": [ "Jobs" ], "summary": "Retry job", "description": "Creates a fresh job from the original input. Only failed or cancelled jobs can be retried.", "operationId": "job-retry-post", "deprecated": false, "security": [ { "browserSession": [] }, { "projectApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job id.", "schema": { "type": "string" }, "example": "failed-job-id" } ], "responses": { "202": { "description": "Retry job created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ], "additionalProperties": false }, "example": { "job_id": "new-job-id" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "INSUFFICIENT_CREDITS", "message": "Insufficient credits", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "NOT_FOUND", "message": "Job not found", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } }, "409": { "description": "Only failed or cancelled jobs can be retried", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "example": { "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "Only failed or cancelled jobs can be retried", "request_id": "req_7f8d0a3f-2d54-4b31-b3a9-f769d4f2c91b" } } } } } }, "x-imageextract-credits": null, "x-imageextract-rate-limit": null, "x-imageextract-idempotency": null, "x-imageextract-auth-mode": "session_or_api_key", "x-imageextract-interactive": true } } } }