{"openapi":"3.1.0","info":{"title":"docbeast","version":"1.1.0","description":"Convert scanned PDFs and photos into Excel, CSV or JSON. Send a file, wait for it to finish, and download the result.","termsOfService":"https://docbeast.com/terms","contact":{"email":"hello@docbeast.com"}},"externalDocs":{"description":"Guides and examples","url":"https://docbeast.com/docs"},"servers":[{"url":"https://api.docbeast.com"}],"tags":[{"name":"Conversions","description":"Start a conversion and read its result."},{"name":"Account","description":"Pages used and remaining."}],"paths":{"/v1/convert":{"post":{"operationId":"convert","tags":["Conversions"],"summary":"Start a conversion","description":"Send a PDF, PNG, JPEG, WebP, TIFF or HEIC, up to 25 MB, as the request body or in a form field named file. The file's type is worked out from its contents. Without a key the first page of a file is free, 3 times a day.","security":[{"bearer":[]},{"apiKey":[]},{}],"parameters":[{"name":"mode","in":"query","description":"table keeps rows and columns. text reads the page as plain text.","schema":{"type":"string","enum":["table","text"],"default":"table"}},{"name":"wait","in":"query","description":"Seconds to hold the request open for the result, up to 25. Without it the job comes back queued.","schema":{"type":"integer","minimum":0,"maximum":25,"default":0}},{"name":"filename","in":"query","description":"A name for the file, used to name the downloads. Takes priority over x-filename and the form field's file name.","schema":{"type":"string"}},{"name":"x-filename","in":"header","description":"The same as the filename query parameter.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"image/*":{"schema":{"type":"string","format":"binary"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"Finished within the wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"202":{"description":"Accepted and still queued or running. Check it with GET /v1/jobs/{id}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"The request can't be read. Codes: bad_mode, missing_file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is invalid or revoked. Codes: unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment is needed: a key has no pages left, or the free allowance is used and pay-per-use is on. Codes: credits_used, payment_required, payment_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The file is over 25 MB. Codes: file_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The file isn't a supported type. Codes: unsupported_file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The job failed within the wait. The job's error field says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"429":{"description":"A page or free allowance is used up. Codes: quota_exceeded, free_limit_reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something broke on our side. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-payment-info":{"price":"$0.50","pages":25,"protocols":["mpp"]}}},"/v1/jobs/{id}":{"get":{"operationId":"getJob","tags":["Conversions"],"summary":"Check a conversion","description":"Returns the job as it is now. A failed job is still a 200, with status failed and an error.","parameters":[{"name":"id","in":"path","required":true,"description":"The job's id. It is all that's needed to read the result, so keep it private.","schema":{"type":"string","pattern":"^job_[0-9a-f]{32}$"}}],"responses":{"200":{"description":"The job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"404":{"description":"There is no such job, or it has expired. Codes: not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jobs/{id}/result.{format}":{"get":{"operationId":"getResult","tags":["Conversions"],"summary":"Download the result","description":"Downloads a finished job's result as JSON, CSV or Excel.","parameters":[{"name":"id","in":"path","required":true,"description":"The job's id. It is all that's needed to read the result, so keep it private.","schema":{"type":"string","pattern":"^job_[0-9a-f]{32}$"}},{"name":"format","in":"path","required":true,"schema":{"type":"string","enum":["json","csv","xlsx"]}}],"responses":{"200":{"description":"The file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}},"text/csv":{"schema":{"type":"string"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"There is no such job, or it has expired. Codes: not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The job hasn't finished. Codes: not_ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"The result has been deleted. Codes: expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"operationId":"getUsage","tags":["Account"],"summary":"Pages used and remaining","security":[{"bearer":[]},{"apiKey":[]}],"responses":{"200":{"description":"Usage for the key's plan, or the pages left on a credit key.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PlanUsage"},{"$ref":"#/components/schemas/CreditUsage"}]}}}},"401":{"description":"The key is missing, invalid or revoked. Codes: unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An account key (dbk_live_...) or a credit key (dbk_pack_...)."},"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"The same keys, in a header."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Job":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","failed"]},"filename":{"type":["string","null"]},"page_count":{"type":["integer","null"],"description":"Pages in the document, once known."},"pages_converted":{"type":"integer","description":"Pages read successfully. Only these are counted."},"pages_skipped":{"type":"integer","description":"Pages left out because of a page limit."},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"description":"Set when status is failed."},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","description":"When the job and its files are deleted."},"downloads":{"type":["object","null"],"properties":{"json":{"type":"string"},"csv":{"type":"string"},"xlsx":{"type":"string"}},"description":"Set when status is done."}},"required":["id","status","filename","page_count","pages_converted","pages_skipped","error","created_at","expires_at","downloads"]},"Table":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"array","items":{"type":"string"}}}},"required":["rows"]},"Page":{"type":"object","properties":{"page":{"type":"integer"},"tables":{"type":"array","items":{"$ref":"#/components/schemas/Table"}},"text":{"type":"string","description":"Text outside any table."},"seconds":{"type":"number","description":"How long the page took to read."},"truncated":{"type":"boolean","description":"The page hit a length limit and may be incomplete."},"error":{"type":"string","description":"Set when this page couldn't be read."}},"required":["page","tables","text","seconds","truncated"]},"Result":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":["string","null"]},"page_count":{"type":"integer"},"pages":{"type":"array","items":{"$ref":"#/components/schemas/Page"}}},"required":["id","filename","page_count","pages"]},"PlanUsage":{"type":"object","properties":{"kind":{"const":"plan"},"plan":{"type":"string","enum":["free","starter","pro"]},"period":{"type":"string","description":"The billing period these pages belong to."},"pages_used":{"type":"integer"},"pages_included":{"type":"integer"},"pages_remaining":{"type":"integer"}},"required":["kind","plan","period","pages_used","pages_included","pages_remaining"]},"CreditUsage":{"type":"object","properties":{"kind":{"const":"credits"},"pages_remaining":{"type":"integer"}},"required":["kind","pages_remaining"]}}}}