{"openapi":"3.1.0","info":{"title":"Scan Hero API","description":"\nScan Hero converts any document to Markdown (and 20+ other formats) via a simple REST API.\nUpload once, get clean structured text back — sync for small files, async via webhooks for large ones.\n\n## Authentication\n\nAll endpoints (except `/health`) require one of:\n\n- **API Key** — `X-Api-Key: sh_<your-key>` header (recommended for server-to-server)\n- **Firebase JWT** — `Authorization: Bearer <id-token>` (used by the web dashboard)\n\nGenerate API keys at [scanheroai.com/settings/api-keys](https://www.scanheroai.com/settings/api-keys).\n\n## Credits\n\nEvery conversion costs credits. New accounts start with **100 free credits**.\n\n| Operation | Cost |\n|-----------|------|\n| Conversion (any format, ≤5 MB) | 10 credits |\n| Overage | +1 credit/MB above 5 MB |\n| Audio/Video | 10 + 2 cr/minute |\n| Email batch | 10 + 1 cr/email |\n| LLM adjustment round | token-priced |\n\n## Async vs Sync\n\n- **≤5 MB** — response is immediate with `status: done`\n- **>5 MB** — response has `status: pending`; register a webhook to get notified\n\n## Webhooks\n\n```http\nPOST /v1/webhooks\nContent-Type: application/json\n\n{ \"url\": \"https://your.app/hook\", \"events\": [\"task.completed\", \"task.failed\"] }\n```\n\nPayloads are signed with HMAC-SHA256 using the `signing_secret` returned on create (shown once).\nVerify with header `X-Scan-Hero-Signature: sha256=<sig>` over the raw JSON body.\nReject events with `timestamp` older than 5 minutes (anti-replay — implement on your server).\n\n## Rate limits\n\nCloud Armor enforces per-IP rate limits. API key holders on paid plans have higher quotas.\n\n## Tasks vs direct convert\n\nAlmost every input type uses **one upload endpoint** — there is no separate POST per file format.\n\n| Goal | API |\n|------|-----|\n| Convert PDF, Word, Excel, slides, images, audio, video, email, EPUB, HTML, … | `POST /v1/tasks` with `options_json.output_format` |\n| Export the same task as DOCX, CSV, EPUB, LaTeX, SRT, … | `GET /v1/tasks/{id}/download?format=…` |\n| Binary passthrough **without** a Markdown step (DjVu, legacy PPT→PPTX only) | `POST /v1/convert/…` (3 endpoints — see the **convert** tag) |\n\nThe **convert** tag lists only those three passthrough routes, not every supported input type.\n","termsOfService":"https://www.scanheroai.com/legal/terms","contact":{"name":"Scan Hero Support","url":"https://www.scanheroai.com/","email":"support@scanheroai.com"},"license":{"name":"Proprietary","url":"https://www.scanheroai.com/legal/terms"},"version":"1.0.0"},"servers":[{"url":"https://api.scanheroai.com","description":"Production"}],"paths":{"/v1/tasks/estimate-cost":{"get":{"tags":["tasks"],"summary":"Estimate Cost","description":"Return credit cost estimate for a task.\n\nArgs:\n    size_bytes: File size in bytes.\n    format: MIME type hint (e.g. ``video/mp4``) for format-specific billing.\n    duration_seconds: Known audio/video duration (from frontend probe).\n    email_count: Estimated email count for .pst/.mbox.\n    cloud_pull: Whether the file comes from a cloud source (+5 cr).\n\nReturns:\n    Breakdown of credits.","operationId":"estimate_cost_v1_tasks_estimate_cost_get","parameters":[{"name":"size_bytes","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Size Bytes"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","default":"","title":"Format"}},{"name":"duration_seconds","in":"query","required":false,"schema":{"type":"number","minimum":0.0,"default":0.0,"title":"Duration Seconds"}},{"name":"email_count","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Email Count"}},{"name":"cloud_pull","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Cloud Pull"}},{"name":"scanned_pdf_pages","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Scanned Pdf Pages"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Estimate Cost V1 Tasks Estimate Cost Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/tasks":{"post":{"tags":["tasks"],"summary":"Create Task","description":"Upload a document and run the conversion pipeline.\n\nSupports all Wave 1–4 input formats. Heavy formats (audio, .pst, .mbox)\nare routed to Cloud Run Jobs via the Job Launcher.\n\nArgs:\n    file: Uploaded document (multipart/form-data). Optional when\n          source_url is provided.\n    options_json: JSON-encoded ProcessingOptions.\n    template_id: Template to apply (optional).\n    source_url: Cloud source URL (Wave 3).\n    source_provider: Provider hint for source_url.\n    push_destination_json: JSON-encoded PushDestination (Out-W3).\n    claims: Injected JWT claims.\n    settings: App settings.","operationId":"create_task_v1_tasks_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_create_task_v1_tasks_post"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["tasks"],"summary":"List Tasks","description":"List tasks for the authenticated user (last 15 days, max 50).","operationId":"list_tasks_v1_tasks_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaskResponse"},"title":"Response List Tasks V1 Tasks Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/tasks/{task_id}":{"get":{"tags":["tasks"],"summary":"Get Task","description":"Retrieve a task by ID.","operationId":"get_task_v1_tasks__task_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","title":"Task Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/tasks/{task_id}/adjust":{"post":{"tags":["tasks"],"summary":"Adjust Task","description":"Apply an LLM adjustment round to a completed task.","operationId":"adjust_task_v1_tasks__task_id__adjust_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","title":"Task Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAdjust"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/tasks/{task_id}/download":{"get":{"tags":["tasks"],"summary":"Download Task","description":"Download task output in the requested format.\n\nArgs:\n    task_id: Task UUID.\n    format: Output format (see _FORMAT_MIME keys).\n    delimiter: For csv/tsv — comma, tab, semicolon, pipe.\n    claims: Injected JWT claims.\n    settings: App settings.","operationId":"download_task_v1_tasks__task_id__download_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","title":"Task Id"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","default":"markdown","title":"Format"}},{"name":"delimiter","in":"query","required":false,"schema":{"type":"string","default":"comma","title":"Delimiter"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/jobs":{"post":{"tags":["jobs"],"summary":"Create Job","operationId":"create_job_v1_jobs_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_create_job_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 Jobs","operationId":"list_jobs_v1_jobs_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/JobResponse"},"title":"Response List Jobs V1 Jobs Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/jobs/{job_id}":{"get":{"tags":["jobs"],"summary":"Get Job","operationId":"get_job_v1_jobs__job_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"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"}}}}}}},"/v1/convert/image-to-djvu":{"post":{"tags":["convert"],"summary":"Convert Image To Djvu","description":"Convert a raster image directly to DjVu without any Markdown step.\n\nUses IW44 wavelet compression via ``c44`` (djvulibre-bin).\nDeducts ``credits_per_task`` credits on success.\n\nArgs:\n    file: Image file (PNG, JPEG, TIFF or WEBP), max 50 MB.\n    claims: Injected JWT claims from Firebase auth.\n    settings: Application settings.\n\nReturns:\n    DjVu file as an attachment download stream.","operationId":"convert_image_to_djvu_v1_convert_image_to_djvu_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_convert_image_to_djvu_v1_convert_image_to_djvu_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/convert/doc-to-docx":{"post":{"tags":["convert"],"summary":"Convert Doc To Docx Endpoint","description":"Convert legacy .doc to DOCX via LibreOffice (LO intermediate exposure).","operationId":"convert_doc_to_docx_endpoint_v1_convert_doc_to_docx_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_convert_doc_to_docx_endpoint_v1_convert_doc_to_docx_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/convert/doc-to-pdfa":{"post":{"tags":["convert"],"summary":"Convert Doc To Pdfa Endpoint","description":"Convert legacy .doc to PDF/A via LibreOffice.","operationId":"convert_doc_to_pdfa_endpoint_v1_convert_doc_to_pdfa_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_convert_doc_to_pdfa_endpoint_v1_convert_doc_to_pdfa_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/convert/ppt-to-pptx":{"post":{"tags":["convert"],"summary":"Convert Ppt To Pptx Endpoint","description":"Convert a PPT (binary, legacy) file to PPTX via LibreOffice headless passthrough.\n\nThe PPTX produced by LibreOffice is returned directly as a binary attachment —\nno Markdown intermediate is generated. Deducts ``credits_per_task`` on success.\n\nArgs:\n    file: PPT file (``application/vnd.ms-powerpoint``), max 50 MB.\n    claims: Injected JWT claims from Firebase auth.\n    settings: Application settings.\n\nReturns:\n    PPTX file as an attachment download stream.","operationId":"convert_ppt_to_pptx_endpoint_v1_convert_ppt_to_pptx_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_convert_ppt_to_pptx_endpoint_v1_convert_ppt_to_pptx_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/convert/pdf-to-djvu":{"post":{"tags":["convert"],"summary":"Convert Pdf To Djvu","description":"Convert a PDF to a compressed multi-page DjVu without any Markdown step.\n\nPipeline: pdftoppm (150 DPI) → c44 per page → djvm bundle.\nDeducts ``credits_per_task`` credits on success.\n\nArgs:\n    file: PDF file, max 50 MB.\n    claims: Injected JWT claims from Firebase auth.\n    settings: Application settings.\n\nReturns:\n    Multi-page DjVu file as an attachment download stream.","operationId":"convert_pdf_to_djvu_v1_convert_pdf_to_djvu_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_convert_pdf_to_djvu_v1_convert_pdf_to_djvu_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/templates":{"post":{"tags":["templates"],"summary":"Create Template","description":"Save a new template for the authenticated user.\n\nArgs:\n    body: Template name, options, and accumulated adjust_prompts.\n    claims: Injected JWT claims.\n    settings: App settings.\n\nReturns:\n    Created TemplateResponse.","operationId":"create_template_v1_templates_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["templates"],"summary":"List Templates","description":"List all templates for the authenticated user.\n\nArgs:\n    claims: Injected JWT claims.\n    settings: App settings.\n\nReturns:\n    List of TemplateResponse.","operationId":"list_templates_v1_templates_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TemplateResponse"},"title":"Response List Templates V1 Templates Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/templates/{template_id}":{"get":{"tags":["templates"],"summary":"Get Template","description":"Retrieve a specific template by ID.\n\nArgs:\n    template_id: Template UUID.\n    claims: Injected JWT claims.\n    settings: App settings.\n\nReturns:\n    TemplateResponse.","operationId":"get_template_v1_templates__template_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string","title":"Template Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["templates"],"summary":"Delete Template","description":"Delete a template by ID.\n\nArgs:\n    template_id: Template UUID.\n    claims: Injected JWT claims.\n    settings: App settings.","operationId":"delete_template_v1_templates__template_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string","title":"Template Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/feedback":{"post":{"tags":["feedback"],"summary":"Submit Feedback","description":"Submit a star rating for a completed task and receive a credit cashback.\n\nVerifies task ownership before persisting feedback. Returns 10% of the\ntask's credits as cashback (minimum 1 credit).\n\nArgs:\n    body: Task ID and 0-5 star rating.\n    claims: Injected JWT claims.\n    settings: App settings.\n\nReturns:\n    Created FeedbackResponse with cashback_credits populated.","operationId":"submit_feedback_v1_feedback_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/users/me":{"get":{"tags":["users"],"summary":"Get Me","description":"Return the authenticated user's profile and credit balance.\n\nArgs:\n    claims: Injected JWT claims.\n    settings: App settings.\n\nReturns:\n    UserResponse with current credit balance.","operationId":"get_me_v1_users_me_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks":{"post":{"tags":["webhooks"],"summary":"Create Webhook","description":"Register a new webhook endpoint.\n\nReturns ``signing_secret`` once — store it to verify ``X-Scan-Hero-Signature``.","operationId":"create_webhook_v1_webhooks_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreatedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["webhooks"],"summary":"List Webhooks","description":"List active webhooks for the authenticated user.","operationId":"list_webhooks_v1_webhooks_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookPublicResponse"},"title":"Response List Webhooks V1 Webhooks Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{webhook_id}":{"delete":{"tags":["webhooks"],"summary":"Delete Webhook","description":"Delete (soft-delete) a registered webhook.","operationId":"delete_webhook_v1_webhooks__webhook_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","title":"Webhook Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"tags":["health"],"summary":"Health","description":"Liveness probe endpoint.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Health Health Get"}}}}}}}},"components":{"schemas":{"Body_convert_doc_to_docx_endpoint_v1_convert_doc_to_docx_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_convert_doc_to_docx_endpoint_v1_convert_doc_to_docx_post"},"Body_convert_doc_to_pdfa_endpoint_v1_convert_doc_to_pdfa_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_convert_doc_to_pdfa_endpoint_v1_convert_doc_to_pdfa_post"},"Body_convert_image_to_djvu_v1_convert_image_to_djvu_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_convert_image_to_djvu_v1_convert_image_to_djvu_post"},"Body_convert_pdf_to_djvu_v1_convert_pdf_to_djvu_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_convert_pdf_to_djvu_v1_convert_pdf_to_djvu_post"},"Body_convert_ppt_to_pptx_endpoint_v1_convert_ppt_to_pptx_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_convert_ppt_to_pptx_endpoint_v1_convert_ppt_to_pptx_post"},"Body_create_job_v1_jobs_post":{"properties":{"files":{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array","title":"Files"},"options_json":{"type":"string","title":"Options Json","default":"{}"},"template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Id"}},"type":"object","required":["files"],"title":"Body_create_job_v1_jobs_post"},"Body_create_task_v1_tasks_post":{"properties":{"file":{"anyOf":[{"type":"string","contentMediaType":"application/octet-stream"},{"type":"null"}],"title":"File"},"options_json":{"type":"string","title":"Options Json","default":"{}"},"template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Id"},"adjust_prompts_json":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Adjust Prompts Json"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"source_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Provider"},"push_destination_json":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Push Destination Json"}},"type":"object","title":"Body_create_task_v1_tasks_post"},"FeedbackCreate":{"properties":{"task_id":{"type":"string","title":"Task Id"},"rating":{"type":"integer","maximum":5.0,"minimum":0.0,"title":"Rating"}},"type":"object","required":["task_id","rating"],"title":"FeedbackCreate","description":"Request body for submitting task feedback."},"FeedbackResponse":{"properties":{"feedback_id":{"type":"string","title":"Feedback Id"},"task_id":{"type":"string","title":"Task Id"},"user_id":{"type":"string","title":"User Id"},"rating":{"type":"integer","title":"Rating"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"cashback_credits":{"type":"integer","title":"Cashback Credits","default":0}},"type":"object","required":["feedback_id","task_id","user_id","rating","created_at"],"title":"FeedbackResponse","description":"Feedback payload returned to the client."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"JobItem":{"properties":{"item_id":{"type":"string","title":"Item Id"},"task_id":{"type":"string","title":"Task Id"},"filename":{"type":"string","title":"Filename"},"size_bytes":{"type":"integer","title":"Size Bytes"},"status":{"type":"string","enum":["pending","processing","done","failed"],"title":"Status"},"credits_upfront":{"type":"integer","title":"Credits Upfront","default":10},"credits_on_success":{"type":"integer","title":"Credits On Success","default":0},"credits_charged":{"type":"integer","title":"Credits Charged","default":0},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["item_id","task_id","filename","size_bytes","status"],"title":"JobItem"},"JobResponse":{"properties":{"job_id":{"type":"string","title":"Job Id"},"user_id":{"type":"string","title":"User Id"},"status":{"type":"string","enum":["queued","processing","done","partial","failed"],"title":"Status"},"items":{"items":{"$ref":"#/components/schemas/JobItem"},"type":"array","title":"Items","default":[]},"credits_upfront_total":{"type":"integer","title":"Credits Upfront Total","default":0},"credits_charged_total":{"type":"integer","title":"Credits Charged Total","default":0},"log":{"items":{"type":"string"},"type":"array","title":"Log","default":[]},"created_at":{"type":"string","format":"date-time","title":"Created At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["job_id","user_id","status","created_at"],"title":"JobResponse"},"ProcessingOptions":{"properties":{"output_language":{"type":"string","title":"Output Language","default":"en"},"image_handling":{"type":"string","enum":["ignore","describe","sidecar"],"title":"Image Handling","default":"ignore"},"page_markers":{"type":"boolean","title":"Page Markers","default":false},"output_format":{"type":"string","enum":["markdown","plain_text","json","docx","pdf","csv","tsv","xlsx","odt","ods","epub","latex","rtf","google_docs","google_sheets","notion_push","onedrive","notion_blocks","ndjson","parquet","xml_docbook","yaml_frontmatter","asciidoc","rst","confluence_wiki","srt","vtt","pdf_a","html"],"title":"Output Format","default":"markdown"},"process_attachments":{"type":"boolean","title":"Process Attachments","default":false},"max_emails":{"type":"integer","maximum":10000.0,"minimum":1.0,"title":"Max Emails","default":500},"no_llm":{"type":"boolean","title":"No Llm","default":false},"csv_delimiter":{"type":"string","enum":["comma","tab","semicolon","pipe"],"title":"Csv Delimiter","default":"comma"},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds"},"gif_sample_frames":{"type":"boolean","title":"Gif Sample Frames","default":false},"video_frame_vision":{"type":"boolean","title":"Video Frame Vision","default":false},"stt_confidence":{"type":"boolean","title":"Stt Confidence","default":false}},"type":"object","title":"ProcessingOptions","description":"User-configurable options for a conversion task."},"TaskAdjust":{"properties":{"prompt":{"type":"string","maxLength":2000,"minLength":1,"title":"Prompt"},"save_to_template":{"type":"boolean","title":"Save To Template","default":false},"template_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Name"}},"type":"object","required":["prompt"],"title":"TaskAdjust","description":"Request body for an LLM adjustment round."},"TaskResponse":{"properties":{"task_id":{"type":"string","title":"Task Id"},"user_id":{"type":"string","title":"User Id"},"status":{"type":"string","enum":["pending","processing","done","failed"],"title":"Status"},"options":{"$ref":"#/components/schemas/ProcessingOptions"},"input_filename":{"type":"string","title":"Input Filename"},"output_markdown":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Markdown"},"quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Score"},"judge_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Judge Score"},"judge_feedback":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Judge Feedback"},"embedding_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Embedding Score"},"credits_used":{"type":"integer","title":"Credits Used"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"adjust_prompts":{"items":{"type":"string"},"type":"array","title":"Adjust Prompts"},"pending_adjust_prompts":{"items":{"type":"string"},"type":"array","title":"Pending Adjust Prompts","description":"Template adjustment prompts to run after conversion completes"},"size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size Bytes"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id"},"item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Item Id"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"ab_experiment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ab Experiment Id"},"ab_variant":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ab Variant"},"format_detected":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Format Detected"},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds"},"emails_extracted":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Emails Extracted"},"transcription_language_detected":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transcription Language Detected"},"credits_reserved":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Reserved"},"credits_charged":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Charged"},"credits_refunded":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Refunded"},"input_gcs_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Input Gcs Path"},"sensitive_input_purge_after":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Sensitive Input Purge After"},"sensitive_input_purged_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Sensitive Input Purged At"},"transcription_segments":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Transcription Segments"},"lo_intermediate_gcs_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lo Intermediate Gcs Path"},"attachment_manifest":{"anyOf":[{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array"},{"type":"null"}],"title":"Attachment Manifest"},"direct_output_gcs_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direct Output Gcs Path"}},"type":"object","required":["task_id","user_id","status","options","input_filename","credits_used","created_at"],"title":"TaskResponse","description":"Task payload returned to the client."},"TemplateCreate":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name"},"options":{"$ref":"#/components/schemas/ProcessingOptions"},"adjust_prompts":{"items":{"type":"string"},"type":"array","title":"Adjust Prompts"}},"type":"object","required":["name"],"title":"TemplateCreate","description":"Request body for saving a new template."},"TemplateResponse":{"properties":{"template_id":{"type":"string","title":"Template Id"},"user_id":{"type":"string","title":"User Id"},"name":{"type":"string","title":"Name"},"options":{"$ref":"#/components/schemas/ProcessingOptions"},"adjust_prompts":{"items":{"type":"string"},"type":"array","title":"Adjust Prompts"},"estimated_adjust_credits":{"type":"integer","title":"Estimated Adjust Credits","default":0},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["template_id","user_id","name","options","adjust_prompts","created_at"],"title":"TemplateResponse","description":"Template payload returned to the client."},"UserResponse":{"properties":{"user_id":{"type":"string","title":"User Id"},"email":{"type":"string","title":"Email"},"credits":{"type":"integer","title":"Credits"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"plan":{"type":"string","title":"Plan","default":"free"},"stripe_customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Customer Id"},"plan_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Plan Expires At"},"credits_expire_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Credits Expire At"},"is_admin":{"type":"boolean","title":"Is Admin","default":false},"paypal_subscription_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paypal Subscription Id"}},"type":"object","required":["user_id","email","credits","created_at"],"title":"UserResponse","description":"User payload returned to the client."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebhookCreate":{"properties":{"url":{"type":"string","title":"Url"},"events":{"items":{"type":"string"},"type":"array","title":"Events","default":["task.completed","task.failed"]}},"type":"object","required":["url"],"title":"WebhookCreate"},"WebhookCreatedResponse":{"properties":{"webhook_id":{"type":"string","title":"Webhook Id"},"user_id":{"type":"string","title":"User Id"},"url":{"type":"string","title":"Url"},"events":{"items":{"type":"string"},"type":"array","title":"Events"},"is_active":{"type":"boolean","title":"Is Active","default":true},"created_at":{"type":"string","format":"date-time","title":"Created At"},"signing_secret":{"type":"string","title":"Signing Secret"}},"type":"object","required":["webhook_id","user_id","url","events","created_at","signing_secret"],"title":"WebhookCreatedResponse","description":"Returned once on POST /v1/webhooks — includes the HMAC signing secret."},"WebhookPublicResponse":{"properties":{"webhook_id":{"type":"string","title":"Webhook Id"},"user_id":{"type":"string","title":"User Id"},"url":{"type":"string","title":"Url"},"events":{"items":{"type":"string"},"type":"array","title":"Events"},"is_active":{"type":"boolean","title":"Is Active","default":true},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["webhook_id","user_id","url","events","created_at"],"title":"WebhookPublicResponse","description":"Webhook metadata returned from list/delete — never includes signing secret."}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"tasks","description":"Upload any supported document and convert it — the main API surface. One `POST /v1/tasks` accepts PDF, Word, Excel, slides, images, audio, video, email, EPUB, HTML, and more; set `options_json.output_format` for the initial output. Use `GET /v1/tasks/{id}/download?format=…` to export the same task as DOCX, CSV, EPUB, LaTeX, SRT, etc."},{"name":"jobs","description":"Batch processing — upload up to 50 files in one request."},{"name":"webhooks","description":"Register URLs to receive push notifications when tasks complete."},{"name":"templates","description":"Save reusable processing configurations."},{"name":"users","description":"Retrieve your profile and credit balance."},{"name":"convert","description":"Stateless binary passthrough — **not** the general conversion pipeline. Only three routes, all `POST`, that skip Markdown/LLM: `/image-to-djvu` (PNG/JPEG/TIFF/WEBP → DjVu), `/pdf-to-djvu`, and `/ppt-to-pptx` (legacy PowerPoint). For every other input or output format, use **tasks** instead."},{"name":"feedback","description":"Rate conversion quality and earn cashback credits."},{"name":"health","description":"Liveness probe for load balancers."}]}