{"openapi":"3.1.0","info":{"title":"Formatly API","description":"Document formatting service API","version":"1.0.0"},"paths":{"/api/v1/documents":{"post":{"summary":"Api Create Document","description":"Create a formatting job. `content` is the base64-encoded document bytes.\n\nSend an `Idempotency-Key` header to make retries safe: repeating the request\nwith the same key returns the original job instead of creating a duplicate.","operationId":"api_create_document_api_v1_documents_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiCreateJobRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiJobCreatedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/documents/upload":{"post":{"summary":"Api Upload Document","description":"Create a formatting job from a multipart file upload.\n\nSend an `Idempotency-Key` header to make retries safe.","operationId":"api_upload_document_api_v1_documents_upload_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_api_upload_document_api_v1_documents_upload_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiJobCreatedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/documents/{job_id}":{"get":{"summary":"Api Get Job Status","operationId":"api_get_job_status_api_v1_documents__job_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiJobStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/documents/{job_id}/download":{"get":{"summary":"Api Download Document","description":"Download the formatted document. Use ?encoding=base64 for a JSON wrapper.","operationId":"api_download_document_api_v1_documents__job_id__download_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"encoding","in":"query","required":false,"schema":{"type":"string","default":"binary","title":"Encoding"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/documents/{job_id}/report":{"get":{"summary":"Api Get Job Report","description":"Fetch the Citation & Structure Audit report (json | html | pdf).","operationId":"api_get_job_report_api_v1_documents__job_id__report_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"group_by","in":"query","required":false,"schema":{"type":"string","default":"status","title":"Group By"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","default":"json","title":"Format"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/styles":{"get":{"summary":"Api Get Styles","description":"List supported formatting styles. Requires a valid API key.","operationId":"api_get_styles_api_v1_styles_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/usage":{"get":{"summary":"Api Get Usage","description":"Credit balance and recent transactions for the calling key's user.","operationId":"api_get_usage_api_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiUsageResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/webhooks":{"get":{"summary":"Api List Webhooks","operationId":"api_list_webhooks_api_v1_webhooks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ApiWebhookResponse"},"type":"array","title":"Response Api List Webhooks Api V1 Webhooks Get"}}}}},"security":[{"HTTPBearer":[]}]},"post":{"summary":"Api Create Webhook","operationId":"api_create_webhook_api_v1_webhooks_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiWebhookCreateRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiWebhookResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/webhooks/{webhook_id}":{"delete":{"summary":"Api Delete Webhook","operationId":"api_delete_webhook_api_v1_webhooks__webhook_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/webhooks/{webhook_id}/secret":{"post":{"summary":"Api Rotate Webhook Secret","description":"Rotate the signing secret. Returns the new secret exactly once.","operationId":"api_rotate_webhook_secret_api_v1_webhooks__webhook_id__secret_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiWebhookResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/webhooks/{webhook_id}/test":{"post":{"summary":"Api Test Webhook","description":"Deliver a synthetic document.completed event to verify the endpoint.","operationId":"api_test_webhook_api_v1_webhooks__webhook_id__test_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiWebhookTestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/":{"get":{"summary":"Root","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/documents/create-upload":{"post":{"summary":"Create Upload Url","operationId":"create_upload_url_api_documents_create_upload_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_create_upload_url_api_documents_create_upload_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUploadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/documents/upload-complete":{"post":{"summary":"Upload Complete Webhook","operationId":"upload_complete_webhook_api_documents_upload_complete_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUploadComplete"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/documents/status/{job_id}":{"get":{"summary":"Get Document Status","operationId":"get_document_status_api_documents_status__job_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/documents/report/{job_id}":{"get":{"summary":"Get Document Report","operationId":"get_document_report_api_documents_report__job_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"group_by","in":"query","required":false,"schema":{"type":"string","description":"Group findings by 'status' or 'aspect'","default":"status","title":"Group By"},"description":"Group findings by 'status' or 'aspect'"},{"name":"format","in":"query","required":false,"schema":{"type":"string","description":"Output format: 'json' or 'html'","default":"json","title":"Format"},"description":"Output format: 'json' or 'html'"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/documents/download/{job_id}":{"get":{"summary":"Download Document","operationId":"download_document_api_documents_download__job_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/documents/preview-images/{job_id}":{"post":{"summary":"Get Document Preview Images","description":"Return signed URLs for the stored PNG preview pages if pre-generated, or\nrender them on-demand via ConvertAPI DOCX to PNG. Pages are images, so the\nfrontend never serves a downloadable PDF.\nPreview signed URLs are cached in the database with a 24-hour expiration.","operationId":"get_document_preview_images_api_documents_preview_images__job_id__post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/documents/upload":{"post":{"summary":"Upload Document","description":"EXISTING ENDPOINT: Generate presigned upload URL and create document record - KEPT FOR COMPATIBILITY","operationId":"upload_document_api_documents_upload_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_upload_document_api_documents_upload_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/documents/process":{"post":{"summary":"Process Document","description":"Process a document with formatting (legacy endpoint for backward compatibility)","operationId":"process_document_api_documents_process_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessDocumentRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/formatting/styles":{"get":{"summary":"Get Formatting Styles","operationId":"get_formatting_styles_api_formatting_styles_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/jobs":{"get":{"summary":"List Jobs","description":"List jobs for the authenticated user","operationId":"list_jobs_api_jobs_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/jobs/{job_id}":{"delete":{"summary":"Delete Job","operationId":"delete_job_api_jobs__job_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/files":{"get":{"summary":"List Files","description":"List files (same as jobs for this architecture)","operationId":"list_files_api_files_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/referrals/stats":{"get":{"summary":"Get Referral Stats","description":"Get user referral statistics","operationId":"get_referral_stats_api_v1_referrals_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralStatsResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/referrals/claim":{"post":{"summary":"Claim Referral","description":"Manually claim a referral code if not done during signup","operationId":"claim_referral_api_v1_referrals_claim_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimReferralRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}}},"components":{"schemas":{"ApiCreateJobRequest":{"properties":{"filename":{"type":"string","title":"Filename"},"content":{"type":"string","title":"Content"},"style":{"type":"string","title":"Style"},"trackedChanges":{"type":"boolean","title":"Trackedchanges","default":false},"options":{"additionalProperties":true,"type":"object","title":"Options"}},"type":"object","required":["filename","content","style"],"title":"ApiCreateJobRequest"},"ApiJobCreatedResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"job_id":{"type":"string","title":"Job Id"},"status":{"type":"string","title":"Status"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","job_id","status","message"],"title":"ApiJobCreatedResponse"},"ApiJobStatusResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"job_id":{"type":"string","title":"Job Id"},"status":{"type":"string","title":"Status"},"progress":{"type":"integer","title":"Progress","default":0},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"},"report_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Url"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Warning"}},"type":"object","required":["success","job_id","status"],"title":"ApiJobStatusResponse"},"ApiUsageResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"balance_credits":{"type":"integer","title":"Balance Credits","default":0},"total_purchased_credits":{"type":"integer","title":"Total Purchased Credits","default":0},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"transactions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Transactions"}},"type":"object","required":["success"],"title":"ApiUsageResponse"},"ApiWebhookCreateRequest":{"properties":{"url":{"type":"string","title":"Url"},"events":{"items":{"type":"string"},"type":"array","title":"Events"}},"type":"object","required":["url"],"title":"ApiWebhookCreateRequest"},"ApiWebhookResponse":{"properties":{"id":{"type":"string","title":"Id"},"url":{"type":"string","title":"Url"},"events":{"items":{"type":"string"},"type":"array","title":"Events"},"is_active":{"type":"boolean","title":"Is Active"},"secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Secret"},"last_delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Delivered At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["id","url","events","is_active"],"title":"ApiWebhookResponse"},"ApiWebhookTestResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"delivery_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivery Id"},"response_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Status"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","message"],"title":"ApiWebhookTestResponse"},"Body_api_upload_document_api_v1_documents_upload_post":{"properties":{"file":{"type":"string","format":"binary","title":"File"},"style":{"type":"string","title":"Style"},"trackedChanges":{"type":"boolean","title":"Trackedchanges","default":false},"options":{"type":"string","title":"Options","default":"{}"}},"type":"object","required":["file","style"],"title":"Body_api_upload_document_api_v1_documents_upload_post"},"Body_create_upload_url_api_documents_create_upload_post":{"properties":{"filename":{"type":"string","title":"Filename"},"style":{"type":"string","title":"Style"},"trackedChanges":{"type":"boolean","title":"Trackedchanges","default":false},"paperType":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Papertype"},"file_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"File Size"}},"type":"object","required":["filename","style"],"title":"Body_create_upload_url_api_documents_create_upload_post"},"Body_upload_document_api_documents_upload_post":{"properties":{"filename":{"type":"string","title":"Filename"},"style":{"type":"string","title":"Style"},"trackedChanges":{"type":"boolean","title":"Trackedchanges","default":false},"file_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"File Size"}},"type":"object","required":["filename","style"],"title":"Body_upload_document_api_documents_upload_post"},"ClaimReferralRequest":{"properties":{"referral_code":{"type":"string","title":"Referral Code"}},"type":"object","required":["referral_code"],"title":"ClaimReferralRequest"},"CreateUploadResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"job_id":{"type":"string","title":"Job Id"},"upload_url":{"type":"string","title":"Upload Url"},"upload_token":{"type":"string","title":"Upload Token"},"file_path":{"type":"string","title":"File Path"},"message":{"type":"string","title":"Message"},"upload_headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Upload Headers"}},"type":"object","required":["success","job_id","upload_url","upload_token","file_path","message","upload_headers"],"title":"CreateUploadResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ProcessDocumentRequest":{"properties":{"filename":{"type":"string","title":"Filename"},"content":{"type":"string","title":"Content"},"style":{"type":"string","title":"Style"},"trackedChanges":{"type":"boolean","title":"Trackedchanges","default":false},"options":{"additionalProperties":true,"type":"object","title":"Options"}},"type":"object","required":["filename","content","style"],"title":"ProcessDocumentRequest"},"ReferralStatsResponse":{"properties":{"referral_code":{"type":"string","title":"Referral Code"},"referral_count":{"type":"integer","title":"Referral Count"},"bonus_credits":{"type":"integer","title":"Bonus Credits"},"referral_link":{"type":"string","title":"Referral Link"}},"type":"object","required":["referral_code","referral_count","bonus_credits","referral_link"],"title":"ReferralStatsResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebhookUploadComplete":{"properties":{"job_id":{"type":"string","title":"Job Id"},"file_path":{"type":"string","title":"File Path"},"success":{"type":"boolean","title":"Success"}},"type":"object","required":["job_id","file_path","success"],"title":"WebhookUploadComplete"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}}}