swagger: '2.0' info: # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object version: "2.0.0" title: DocRaptor description: "A native client library for the DocRaptor HTML to PDF/XLS service." termsOfService: "https://docraptor.com/tos" license: name: "MIT" url: "https://mit-license.org/" host: docraptor.com basePath: / schemes: [https] securityDefinitions: basicAuth: type: basic description: Use your API key as the username. Password does not need to be set. produces: - application/json - application/xml - application/pdf - application/vnd.ms-excel - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet paths: /docs: post: operationId: createDoc tags: [Doc] description: > Creates a document synchronously. security: - basicAuth: [] parameters: - name: doc in: body description: The document to be created. required: true schema: $ref: '#/definitions/Doc' responses: 200: description: Successful response schema: type: string format: binary 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 422: description: Unprocessable Entity 500: description: Server Error /hosted_docs: post: operationId: createHostedDoc tags: [Doc] description: > Creates a hosted document synchronously. security: - basicAuth: [] parameters: - name: doc in: body description: The document to be created. required: true schema: $ref: '#/definitions/Doc' responses: 200: description: Successful response schema: $ref: '#/definitions/DocStatus' 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 422: description: Unprocessable Entity 500: description: Server Error /async_docs: post: operationId: createAsyncDoc tags: [Doc] description: > Creates a document asynchronously. You must use a callback url or the returned status id and the status API to find out when it completes. Then use the download API to get the document. security: - basicAuth: [] parameters: - name: doc in: body description: The document to be created. required: true schema: $ref: '#/definitions/Doc' responses: 200: description: Successful response schema: $ref: '#/definitions/AsyncDoc' 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 422: description: Unprocessable Entity 500: description: Server Error /hosted_async_docs: post: operationId: createHostedAsyncDoc tags: [Doc] description: > Creates a hosted document asynchronously. You must use a callback url or the returned status id and the status API to find out when it completes. Then use the download API to get the document. security: - basicAuth: [] parameters: - name: doc in: body description: The document to be created. required: true schema: $ref: '#/definitions/Doc' responses: 200: description: Successful response schema: $ref: '#/definitions/AsyncDoc' 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 422: description: Unprocessable Entity 500: description: Server Error /status/{id}: get: operationId: getAsyncDocStatus tags: [Doc] description: > Check on the status of an asynchronously created document. security: - basicAuth: [] parameters: - name: id in: path description: The status_id returned when creating an asynchronous document. required: true type: string responses: 200: description: Successful response schema: $ref: '#/definitions/DocStatus' 401: description: Unauthorized 403: description: Forbidden 500: description: Server Error /download/{id}: get: operationId: getAsyncDoc tags: [Doc] description: > Downloads a finished document. security: - basicAuth: [] parameters: - name: id in: path description: The download_id returned from an async status request or callback. required: true type: string responses: 200: description: Successful response schema: type: string format: binary 400: description: Bad Request 403: description: Forbidden 500: description: Server Error /expire/{id}: patch: operationId: expire tags: [Doc] description: > Expires a previously created hosted doc. security: - basicAuth: [] parameters: - name: id in: path description: The download_id returned from status request or hosted document response. required: true type: string responses: 200: description: Successful response 401: description: Unauthorized 403: description: Forbidden 500: description: Server Error definitions: Doc: type: object required: - name - document_type - document_content properties: name: type: string description: A name for identifying your document. document_type: type: string description: The type of document being created. enum: - pdf - xls - xlsx document_content: type: string description: > The HTML data to be transformed into a document. You must supply content using document_content or document_url. document_url: type: string description: > The URL to fetch the HTML data to be transformed into a document. You must supply content using document_content or document_url. test: type: boolean description: Enable test mode for this document. Test documents are not charged for but include a watermark. default: true pipeline: type: string description: Specify a specific verison of the DocRaptor Pipeline to use. strict: type: string description: Force strict HTML validation. enum: - none - html ignore_resource_errors: type: boolean description: Failed loading of images/javascripts/stylesheets/etc. will not cause the rendering to stop. default: true ignore_console_messages: type: boolean description: Prevent console.log from stopping document rendering during JavaScript execution. default: false tag: type: string description: A field for storing a small amount of metadata with this document. help: type: boolean description: Request support help with this request if it succeeds. default: false javascript: type: boolean description: Enable DocRaptor JavaScript parsing. PrinceXML JavaScript parsing is also available elsewhere. default: false referrer: type: string description: Set HTTP referrer when generating this document. callback_url: type: string description: > A URL that will receive a POST request after successfully completing an asynchronous document. The POST data will include download_url and download_id similar to status API responses. WARNING: this only works on asynchronous documents. hosted_download_limit: type: integer description: The number of times a hosted document can be downloaded. If no limit is specified, the document will be available for an unlimited number of downloads. hosted_expires_at: type: string description: The date and time at which a hosted document will be removed and no longer available. Must be a properly formatted ISO 8601 datetime, like 1981-01-23T08:02:30-05:00. prince_options: $ref: '#/definitions/PrinceOptions' PrinceOptions: type: object properties: baseurl: type: string description: Set the baseurl for assets. no_xinclude: type: boolean description: Disable XML inclusion. no_network: type: boolean description: Disable network access. no_parallel_downloads: type: boolean description: Disables parallel fetching of assets during PDF creation. Useful if your asset host has strict rate limiting. http_user: type: string description: Set the user for HTTP authentication. http_password: type: string description: Set the password for HTTP authentication. http_proxy: type: string description: Set the HTTP proxy server. http_timeout: type: integer description: Set the HTTP request timeout. # default: 10 insecure: type: boolean description: Disable SSL verification. # default: false media: type: string description: Specify the CSS media type. Defaults to "print" but you may want to use "screen" for web styles. default: print no_author_style: type: boolean description: Ignore author stylesheets. no_default_style: type: boolean description: Ignore default stylesheets. no_embed_fonts: type: boolean description: Disable font embedding in PDFs. no_subset_fonts: type: boolean description: Disable font subsetting in PDFs. no_compress: type: boolean description: Disable PDF compression. encrypt: type: boolean description: Encrypt PDF output. key_bits: type: integer description: Set encryption key size. enum: - 40 - 128 user_password: type: string description: Set the PDF user password. owner_password: type: string description: Set the PDF owner password. disallow_print: type: boolean description: Disallow printing of this PDF. disallow_copy: type: boolean description: Disallow copying of this PDF. disallow_annotate: type: boolean description: Disallow annotation of this PDF. disallow_modify: type: boolean description: Disallow modification of this PDF. debug: type: boolean description: Enable Prince debug mode. input: type: string description: Specify the input format. default: html enum: - html - xml - auto version: type: string deprecated: true description: Deprecated, use the appropriate `pipeline` version. Specify a specific verison of PrinceXML to use. # default: 10 # disabled because Java will try to make an enum as 7_1 which fails # enum: # - 7.1 # - 8.1 # - 9.0 # - 10 javascript: type: boolean description: Enable PrinceXML JavaScript. DocRaptor JavaScript parsing is also available elsewhere. css_dpi: type: integer description: Set the DPI when rendering CSS. Defaults to 96 but can be set with Prince 9.0 and up. # default: 96 profile: type: string description: In Prince 9.0 and up you can set the PDF profile. # disabled because Java will try to make an enum with PDF/A-1b which fails # enum: # - PDF/A-1b # - PDF/A-3b # (Pipeline 6+) # - PDF/X-1a # (Pipeline 6+) # - PDF/X-3:2003 # - PDF/X-4 pdf_title: type: string description: Specify the PDF title, part of the document's metadata. AsyncDoc: type: object properties: status_id: type: string description: The identifier used to get the status of the document using the status API. DocStatus: type: object properties: status: type: string description: The present status of the document. Can be queued, working, completed, and failed. download_url: type: string description: The URL where the document can be retrieved. This URL may only be used a few times. download_id: type: string description: The identifier for downloading the document with the download API. message: type: string description: Additional information. number_of_pages: type: integer description: Number of PDF pages in document. validation_errors: type: string description: Error information.