{"openapi":"3.1.0","info":{"title":"Aretus converter API","description":"Converts Microsoft Publisher (.pub) files for aretus.app. Contract: docs/api-contract.md. Not affiliated with Microsoft.","version":"1.0.0"},"servers":[{"url":"https://api.aretus.app"}],"paths":{"/health":{"get":{"tags":["service"],"summary":"Liveness and queue length","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/jobs":{"post":{"tags":["jobs"],"summary":"Upload a batch, or the first part of one","description":"Streamed multipart upload; see docs/api-contract.md for limits and multi-part uploads.","operationId":"post_job_jobs_post","requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"turnstile_token":{"type":"string","description":"Cloudflare Turnstile token. Send it first."},"parts":{"type":"integer","maximum":200.0,"minimum":1.0,"description":"How many requests the batch is split into (each at most 95 MB).","default":1},"files":{"items":{"type":"string","format":"binary"},"type":"array","description":"Repeated. .pub or .zip; each part's filename is the file's relative path."}},"type":"object","required":["turnstile_token","files"]}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Busy or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{job_id}/parts":{"post":{"tags":["jobs"],"summary":"Upload part 2..N of a multi-part batch","description":"Part 2..N of a multi-part upload. The upload token (from POST /jobs) is the only auth.","operationId":"post_part_jobs__job_id__parts_post","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/Job"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Busy or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"upload_token":{"type":"string","description":"upload.token from POST /jobs. Send it first."},"part":{"type":"integer","minimum":2,"description":"This part's number, 2..parts. Send it before the files."},"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"Repeated. .pub or .zip; each part's filename is the file's relative path."}},"required":["upload_token","part","files"]}}}}}},"/jobs/{job_id}":{"get":{"tags":["jobs"],"summary":"A batch's status, files, previews and plan","operationId":"get_job_jobs__job_id__get","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/Job"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/jobs/{job_id}/checkout":{"post":{"tags":["payments"],"summary":"Create the Paddle transaction for the plan","operationId":"checkout_jobs__job_id__checkout_post","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/CheckoutSession"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Busy or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/jobs/{job_id}/free-download":{"post":{"tags":["downloads"],"summary":"One file free, once per email and batch","operationId":"free_download_jobs__job_id__free_download_post","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/SignedUrl"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"email":{"title":"Email","type":"string"},"file_id":{"title":"File Id","type":"string"}},"required":["email","file_id"],"title":"FreeDownloadRequest","type":"object"}}}}}},"/jobs/{job_id}/files/{file_id}/report":{"post":{"tags":["reports"],"summary":"Report a file that didn't convert well","operationId":"report_jobs__job_id__files__file_id__report_post","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"file_id","in":"path","required":true,"schema":{"type":"string","title":"File Id"}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportCreated"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"problems":{"items":{"enum":["text_overlaps","text_missing","fonts","pictures","layout","pages","other"],"type":"string"},"title":"Problems","type":"array"},"note":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"title":"Note"},"keep_file":{"title":"Keep File","type":"boolean"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"}},"required":["problems","keep_file"],"title":"ReportRequest","type":"object"}}}}}},"/jobs/{job_id}/download":{"get":{"tags":["downloads"],"summary":"Signed link to the paid batch's ZIP","operationId":"download_jobs__job_id__download_get","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/SignedUrl"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/webhooks/paddle":{"post":{"tags":["payments"],"summary":"Paddle Billing webhook (server to server)","description":"transaction.completed, verified by the Paddle-Signature header. Not for clients.","operationId":"paddle_webhook_webhooks_paddle_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/files/{key}":{"get":{"tags":["downloads"],"summary":"Signed, expiring file link (previews and ZIPs)","description":"Paid batch ZIPs are always served. Previews and free-file ZIPs share a daily data budget (UNPAID_EGRESS_MB_PER_DAY); past it they get 503 server_busy until midnight UTC.","operationId":"serve_file_files__key__get","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","title":"Key"}}],"responses":{"200":{"description":"The file","content":{"application/json":{"schema":{}},"application/octet-stream":{}}},"206":{"description":"Part of the file (Range request)"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Busy or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/mcp":{"post":{"tags":["mcp"],"summary":"MCP server (Streamable HTTP, stateless, JSON responses)","description":"Model Context Protocol endpoint for AI assistants. JSON-RPC 2.0 over HTTP POST: initialize, tools/list, tools/call (tools: convert_publisher_files, get_conversion, get_free_file, get_pricing). Anonymous; send Accept: application/json, text/event-stream. See docs/mcp.md.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"JSON-RPC response","content":{"application/json":{}}},"429":{"description":"Rate limited (per client IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"CheckoutSession":{"properties":{"provider":{"type":"string","const":"paddle","title":"Provider"},"transaction_id":{"type":"string","title":"Transaction Id","description":"Open Paddle.js v2's overlay checkout with this id."},"environment":{"type":"string","enum":["sandbox","production"],"title":"Environment"}},"type":"object","required":["provider","transaction_id","environment"],"title":"CheckoutSession"},"Counts":{"properties":{"total":{"type":"integer","title":"Total"},"converted":{"type":"integer","title":"Converted"},"failed":{"type":"integer","title":"Failed"},"pending":{"type":"integer","title":"Pending"}},"type":"object","required":["total","converted","failed","pending"],"title":"Counts"},"Error":{"properties":{"error":{"description":"Machine-readable code, e.g. rate_limited, zip_rejected.","title":"Error","type":"string"},"message":{"description":"Plain English, fit to show to the user as is.","title":"Message","type":"string"},"retry_after":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Seconds to wait (429, 503, 409 preparing), also in Retry-After.","title":"Retry After"}},"required":["error","message"],"title":"Error","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Health":{"properties":{"status":{"type":"string","const":"ok","title":"Status"},"queued_files":{"type":"integer","title":"Queued Files"}},"type":"object","required":["status","queued_files"],"title":"Health"},"Job":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"32 hex characters; the only secret giving access to the batch."},"status":{"type":"string","enum":["uploading","queued","processing","ready","failed"],"title":"Status"},"created_at":{"type":"string","title":"Created At"},"expires_at":{"type":"string","title":"Expires At","description":"created_at + 24 h; everything is deleted then."},"counts":{"$ref":"#/components/schemas/Counts"},"plan":{"anyOf":[{"$ref":"#/components/schemas/PlanInfo"},{"type":"null"}],"description":"Chosen from the number of converted files once ready."},"paid":{"type":"boolean","title":"Paid"},"free_launch":{"type":"boolean","title":"Free Launch","description":"Launch offer: GET /jobs/{id}/download works without payment."},"free_download_used":{"type":"boolean","title":"Free Download Used"},"downloads_ready":{"type":"boolean","title":"Downloads Ready","description":"Ready, and every converted file's outputs_ready: the paid ZIP can be built. Checkout doesn't wait for it."},"files":{"items":{"$ref":"#/components/schemas/JobFile"},"type":"array","title":"Files"},"skipped":{"items":{"$ref":"#/components/schemas/Skipped"},"type":"array","title":"Skipped"},"upload":{"anyOf":[{"$ref":"#/components/schemas/UploadState"},{"type":"null"}],"description":"Only for jobs created with parts > 1."}},"type":"object","required":["job_id","status","created_at","expires_at","counts","plan","paid","free_launch","free_download_used","downloads_ready","files","skipped"],"title":"Job"},"JobFile":{"properties":{"id":{"type":"string","title":"Id","description":"\"f1\", \"f2\", ... in upload order."},"path":{"type":"string","title":"Path","description":"Relative path as uploaded."},"size_bytes":{"type":"integer","title":"Size Bytes"},"status":{"type":"string","enum":["queued","processing","converted","failed"],"title":"Status"},"pages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Plain-English reason when failed."},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Font and blank-page warnings join the list when outputs_ready turns true."},"outputs_ready":{"type":"boolean","title":"Outputs Ready","description":"Converted and every format made (DOCX and page images come in a second pass, after the batch's previews). The free download waits for it."},"preview":{"anyOf":[{"$ref":"#/components/schemas/Preview"},{"type":"null"}],"description":"Only the first 10 files of a batch, at most 30 pages each."},"reported":{"type":"boolean","title":"Reported"}},"type":"object","required":["id","path","size_bytes","status","pages","error","warnings","outputs_ready","preview","reported"],"title":"JobFile"},"PlanInfo":{"properties":{"id":{"type":"string","enum":["starter","small","archive","organization"],"title":"Id"},"price_usd":{"type":"integer","title":"Price Usd"},"file_limit":{"type":"integer","title":"File Limit"}},"type":"object","required":["id","price_usd","file_limit"],"title":"PlanInfo"},"Preview":{"properties":{"pages":{"items":{"$ref":"#/components/schemas/PreviewPage"},"type":"array","title":"Pages"}},"type":"object","required":["pages"],"title":"Preview"},"PreviewPage":{"properties":{"n":{"type":"integer","title":"N"},"url":{"type":"string","title":"Url","description":"Signed link to a watermarked 72 dpi PNG; expires in about an hour."},"width":{"type":"integer","title":"Width"},"height":{"type":"integer","title":"Height"}},"type":"object","required":["n","url","width","height"],"title":"PreviewPage"},"ReportCreated":{"properties":{"report_id":{"type":"string","title":"Report Id"}},"type":"object","required":["report_id"],"title":"ReportCreated"},"SignedUrl":{"properties":{"url":{"type":"string","title":"Url"},"expires_at":{"type":"string","title":"Expires At"}},"type":"object","required":["url","expires_at"],"title":"SignedUrl"},"Skipped":{"properties":{"path":{"type":"string","title":"Path"},"reason":{"type":"string","title":"Reason"}},"type":"object","required":["path","reason"],"title":"Skipped"},"UploadState":{"properties":{"token":{"type":"string","title":"Token","description":"Authorizes POST /jobs/{job_id}/parts for this job."},"parts":{"type":"integer","title":"Parts"},"received":{"type":"integer","title":"Received"},"missing":{"items":{"type":"integer"},"type":"array","title":"Missing"}},"type":"object","required":["token","parts","received","missing"],"title":"UploadState"},"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"}}}}