{ "openapi": "3.1.0", "info": { "title": "BestPDFEver API", "version": "1.0.0", "description": "Convert, compress, OCR, merge and secure PDFs over HTTP. Jobs are asynchronous: create a job, poll its status (or receive a webhook), then download the results." }, "servers": [ { "url": "https://api.bestpdfever.com" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Organize" }, { "name": "Optimize" }, { "name": "Convert to PDF" }, { "name": "Convert from PDF" }, { "name": "Security" }, { "name": "Jobs" }, { "name": "Account" } ], "paths": { "/v1/merge": { "post": { "operationId": "merge", "summary": "Merge PDF", "description": "Combine 2–20 PDFs into one, in the order you send them.\n\nCost: 1 credit per successful job. Accepted files: .pdf (2–20).", "tags": [ "Organize" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/split": { "post": { "operationId": "split", "summary": "Split PDF", "description": "Split a PDF into one file per page, or into the page ranges you choose.\n\nCost: 1 credit per successful job. Accepted files: .pdf (1).", "tags": [ "Organize" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": { "ranges": { "description": "Comma-separated page ranges, one output file per range, e.g. \"1-3,4,5-9\". Omit to split every page into its own file.", "type": "string", "examples": [ "1-3,4-6" ] } }, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": { "ranges": { "description": "Comma-separated page ranges, one output file per range, e.g. \"1-3,4,5-9\". Omit to split every page into its own file.", "type": "string", "examples": [ "1-3,4-6" ] } }, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/rotate": { "post": { "operationId": "rotate", "summary": "Rotate PDF", "description": "Rotate all pages, or only the pages you list, clockwise.\n\nCost: 1 credit per successful job. Accepted files: .pdf (1).", "tags": [ "Organize" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": { "angle": { "description": "Clockwise rotation in degrees.", "type": "integer", "enum": [ 90, 180, 270 ], "default": 90 }, "pages": { "description": "Page ranges to rotate, e.g. \"1,3-5\". Omit to rotate every page.", "type": "string", "examples": [ "1,3-5" ] } }, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": { "angle": { "description": "Clockwise rotation in degrees.", "type": "integer", "enum": [ 90, 180, 270 ], "default": 90 }, "pages": { "description": "Page ranges to rotate, e.g. \"1,3-5\". Omit to rotate every page.", "type": "string", "examples": [ "1,3-5" ] } }, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/compress": { "post": { "operationId": "compress", "summary": "Compress PDF", "description": "Shrink a PDF by downsampling images and removing redundant data.\n\nCost: 2 credits per successful job. Accepted files: .pdf (1).", "tags": [ "Optimize" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": { "level": { "description": "How hard to compress. Ignored when targetKB is set.", "type": "string", "enum": [ "low", "recommended", "extreme" ], "default": "recommended" }, "targetKB": { "description": "Try to get the file under this size in kilobytes.", "type": "integer", "examples": [ 500 ], "minimum": 20, "maximum": 100000 }, "grayscale": { "description": "Convert to grayscale for extra savings.", "type": "boolean", "default": false } }, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": { "level": { "description": "How hard to compress. Ignored when targetKB is set.", "type": "string", "enum": [ "low", "recommended", "extreme" ], "default": "recommended" }, "targetKB": { "description": "Try to get the file under this size in kilobytes.", "type": "integer", "examples": [ 500 ], "minimum": 20, "maximum": 100000 }, "grayscale": { "description": "Convert to grayscale for extra savings.", "type": "boolean", "default": false } }, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/repair": { "post": { "operationId": "repair", "summary": "Repair PDF", "description": "Rebuild a damaged or partly corrupted PDF.\n\nCost: 1 credit per successful job. Accepted files: .pdf (1).", "tags": [ "Optimize" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/ocr": { "post": { "operationId": "ocr", "summary": "OCR PDF", "description": "Add a searchable, selectable text layer to scanned PDFs.\n\nCost: 3 credits per successful job. Accepted files: .pdf (1).", "tags": [ "Optimize" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": { "languages": { "description": "1–3 Tesseract language codes: eng, spa, por, fra, deu, ita, nld, ind, swa, hin, ara, rus, tur, vie, chi_sim, jpn, kor.", "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 3, "default": [ "eng" ], "examples": [ [ "eng", "fra" ] ] }, "deskew": { "description": "Straighten crooked scans.", "type": "boolean", "default": true }, "force": { "description": "Re-OCR pages that already contain text.", "type": "boolean", "default": false } }, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": { "languages": { "description": "1–3 Tesseract language codes: eng, spa, por, fra, deu, ita, nld, ind, swa, hin, ara, rus, tur, vie, chi_sim, jpn, kor.", "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 3, "default": [ "eng" ], "examples": [ [ "eng", "fra" ] ] }, "deskew": { "description": "Straighten crooked scans.", "type": "boolean", "default": true }, "force": { "description": "Re-OCR pages that already contain text.", "type": "boolean", "default": false } }, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/convert/word-to-pdf": { "post": { "operationId": "convert-word-to-pdf", "summary": "Word to PDF", "description": "Convert DOC, DOCX, ODT, RTF or TXT to PDF. Up to 10 files, one PDF each.\n\nCost: 2 credits per successful job. Accepted files: .doc, .docx, .odt, .rtf, .txt (1–10).", "tags": [ "Convert to PDF" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/convert/powerpoint-to-pdf": { "post": { "operationId": "convert-powerpoint-to-pdf", "summary": "PowerPoint to PDF", "description": "Convert PPT, PPTX, ODP, PPS or PPSX to PDF. Up to 10 files.\n\nCost: 2 credits per successful job. Accepted files: .ppt, .pptx, .odp, .pps, .ppsx (1–10).", "tags": [ "Convert to PDF" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/convert/excel-to-pdf": { "post": { "operationId": "convert-excel-to-pdf", "summary": "Excel to PDF", "description": "Convert XLS, XLSX, ODS or CSV to PDF. Up to 10 files.\n\nCost: 2 credits per successful job. Accepted files: .xls, .xlsx, .ods, .csv (1–10).", "tags": [ "Convert to PDF" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/convert/html-to-pdf": { "post": { "operationId": "convert-html-to-pdf", "summary": "HTML / URL to PDF", "description": "Render a public web page or an uploaded HTML file to PDF with a real browser.\n\nCost: 2 credits per successful job. Accepted files: .html, .htm (0–1).", "tags": [ "Convert to PDF" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": { "url": { "description": "Public page to render. Send this instead of a file.", "type": "string", "examples": [ "https://example.com" ] }, "format": { "description": "Paper size.", "type": "string", "enum": [ "A4", "Letter", "Legal" ], "default": "A4" }, "landscape": { "description": "Landscape orientation.", "type": "boolean", "default": false }, "margin": { "description": "Page margins.", "type": "string", "enum": [ "none", "small", "normal" ], "default": "small" }, "background": { "description": "Print background colors and images.", "type": "boolean", "default": true }, "media": { "description": "CSS media type to emulate.", "type": "string", "enum": [ "print", "screen" ], "default": "screen" } }, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": { "url": { "description": "Public page to render. Send this instead of a file.", "type": "string", "examples": [ "https://example.com" ] }, "format": { "description": "Paper size.", "type": "string", "enum": [ "A4", "Letter", "Legal" ], "default": "A4" }, "landscape": { "description": "Landscape orientation.", "type": "boolean", "default": false }, "margin": { "description": "Page margins.", "type": "string", "enum": [ "none", "small", "normal" ], "default": "small" }, "background": { "description": "Print background colors and images.", "type": "boolean", "default": true }, "media": { "description": "CSS media type to emulate.", "type": "string", "enum": [ "print", "screen" ], "default": "screen" } }, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/convert/pdf-to-word": { "post": { "operationId": "convert-pdf-to-word", "summary": "PDF to Word", "description": "Convert a PDF to an editable DOCX.\n\nCost: 2 credits per successful job. Accepted files: .pdf (1).", "tags": [ "Convert from PDF" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/convert/pdf-to-powerpoint": { "post": { "operationId": "convert-pdf-to-powerpoint", "summary": "PDF to PowerPoint", "description": "Convert each PDF page into a slide with editable text.\n\nCost: 2 credits per successful job. Accepted files: .pdf (1).", "tags": [ "Convert from PDF" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/convert/pdf-to-excel": { "post": { "operationId": "convert-pdf-to-excel", "summary": "PDF to Excel", "description": "Extract tables from a PDF into an XLSX workbook.\n\nCost: 2 credits per successful job. Accepted files: .pdf (1).", "tags": [ "Convert from PDF" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": { "mode": { "description": "\"tables\": one sheet per detected table. \"pages\": one sheet per page with all text.", "type": "string", "enum": [ "tables", "pages" ], "default": "tables" } }, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": { "mode": { "description": "\"tables\": one sheet per detected table. \"pages\": one sheet per page with all text.", "type": "string", "enum": [ "tables", "pages" ], "default": "tables" } }, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/convert/pdf-to-pdfa": { "post": { "operationId": "convert-pdf-to-pdfa", "summary": "PDF to PDF/A", "description": "Convert to PDF/A for long-term archiving.\n\nCost: 2 credits per successful job. Accepted files: .pdf (1).", "tags": [ "Convert from PDF" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": { "level": { "description": "PDF/A conformance level (PDF/A-1b, -2b or -3b).", "type": "string", "enum": [ "1", "2", "3" ], "default": "2" } }, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": { "level": { "description": "PDF/A conformance level (PDF/A-1b, -2b or -3b).", "type": "string", "enum": [ "1", "2", "3" ], "default": "2" } }, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/protect": { "post": { "operationId": "protect", "summary": "Protect PDF", "description": "Encrypt a PDF with a password (AES-256) and set permissions.\n\nCost: 1 credit per successful job. Accepted files: .pdf (1).", "tags": [ "Security" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": { "userPassword": { "description": "Password needed to open the file.", "type": "string", "examples": [ "s3cret" ] }, "ownerPassword": { "description": "Password that unlocks the permissions. Defaults to a random one.", "type": "string" }, "allowPrinting": { "description": "Allow printing.", "type": "boolean", "default": true }, "allowCopying": { "description": "Allow copying text and images.", "type": "boolean", "default": false }, "allowEditing": { "description": "Allow editing and annotations.", "type": "boolean", "default": false } }, "required": [ "userPassword" ] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": { "userPassword": { "description": "Password needed to open the file.", "type": "string", "examples": [ "s3cret" ] }, "ownerPassword": { "description": "Password that unlocks the permissions. Defaults to a random one.", "type": "string" }, "allowPrinting": { "description": "Allow printing.", "type": "boolean", "default": true }, "allowCopying": { "description": "Allow copying text and images.", "type": "boolean", "default": false }, "allowEditing": { "description": "Allow editing and annotations.", "type": "boolean", "default": false } }, "required": [ "userPassword" ] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/unlock": { "post": { "operationId": "unlock", "summary": "Unlock PDF", "description": "Remove the password and restrictions from a PDF you have the password for.\n\nCost: 1 credit per successful job. Accepted files: .pdf (1).", "tags": [ "Security" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat the field for several files, in order." }, "url": { "type": "string", "format": "uri", "description": "Public URL of an input file (repeatable). Use instead of uploading." }, "options": { "type": "string", "description": "JSON object with the options below.", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": false, "properties": { "password": { "description": "The document's password. Leave empty for files with only permission restrictions.", "type": "string", "default": "" } }, "required": [] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Paid plans: POSTed when the job finishes." } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 }, "options": { "type": "object", "additionalProperties": false, "properties": { "password": { "description": "The document's password. Leave empty for files with only permission restrictions.", "type": "string", "default": "" } }, "required": [] }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreated" } } } }, "400": { "description": "Invalid input, options or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly credits used up (Free plan)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large for the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Endpoint temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/jobs/{id}": { "get": { "operationId": "getJob", "summary": "Get job status", "description": "Poll until status is done or failed. Download URLs expire after 15 minutes; files are deleted after an hour.", "tags": [ "Jobs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "404": { "description": "Unknown job, or not yours", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/account": { "get": { "operationId": "getAccount", "summary": "Plan and usage", "tags": [ "Account" ], "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from the developer dashboard (bpe_live_…)." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "examples": [ "invalid_api_key" ] }, "message": { "type": "string" }, "detail": { "type": "string" } } }, "JobCreated": { "type": "object", "required": [ "id", "status", "credits", "statusUrl" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "const": "queued" }, "credits": { "type": "integer" }, "statusUrl": { "type": "string", "format": "uri" } } }, "Job": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "queued", "active", "done", "failed" ] }, "progress": { "type": "number", "minimum": 0, "maximum": 1 }, "position": { "type": "integer", "description": "Place in the queue while queued." }, "error": { "type": "string", "description": "Failure code, e.g. wrong_password, conversion_failed, timeout." }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "size": { "type": "integer" }, "contentType": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } } }, "Account": { "type": "object", "properties": { "email": { "type": "string" }, "plan": { "type": "object", "properties": { "id": { "enum": [ "free", "starter", "pro", "business" ] }, "name": { "type": "string" }, "credits": { "type": "integer" }, "rateLimitPerMinute": { "type": "integer" }, "maxFileMB": { "type": "integer" }, "webhooks": { "type": "boolean" } } }, "period": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" } } }, "usage": { "type": "object", "properties": { "credits": { "type": "integer" }, "requests": { "type": "integer" }, "remaining": { "type": "integer" } } } } } } } }