docraptor.yaml

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.