openapi: 3.0.3
info:
  description: |-
    Carbone Open API reference.

    The Carbone API streamlines dynamic document generation and template management, offering robust features for creating and customizing documents across various industries and professional fields. With support for uploading templates and generating documents by merging templates with JSON datasets, Carbone facilitates seamless integration across numerous document formats. Key industries and applications include:
      - Finance and Accounting: Automated generation of invoices, financial reports, and tax statements.
      - Healthcare: Creation of patient records, medical reports, and insurance documents.
      - Legal: Generating contracts, legal agreements, and court documentation.
      - Human Resources: Automating employee onboarding papers, contracts, and internal communications.
      - Retail and E-commerce: Producing receipts, shipping labels, and promotional materials.
      - Education: Crafting certificates, transcripts, and administrative documents.
    
    To get started:
    - **Carbone Cloud API**: find your API key on your [Carbone account](https://account.carbone.io). Home page > Copy the `production` or `test` API key.
    - **Carbone Docker**: Update the `servers.url` field on the Open API specification.
    - **Carbone On-premise**: Update the `servers.url` field on the Open API specification.
    - **Carbone On-AWS**: Update the `servers.url` field on the Open API specification.
    
    Documentation:
    - [Authentication](https://carbone.io/documentation/developer/http-api/introduction.html#authentication)
    - [API Flow](https://carbone.io/documentation/developer/http-api/introduction.html#api-flow)
    - [API Timeout](https://carbone.io/documentation/developer/http-api/introduction.html#api-timeout)
    - [API Webhooks](https://carbone.io/documentation/developer/http-api/introduction.html#api-webhook)
    - [API Versions](https://carbone.io/documentation/developer/http-api/introduction.html#api-version)
    - [Template Storage](https://carbone.io/documentation/developer/http-api/introduction.html#template-storage)
    - [Document Storage](https://carbone.io/documentation/developer/http-api/introduction.html#report-storage)
    - SDKs: [Node](https://carbone.io/documentation/developer/api-sdks/nodejs.html), [Javascript](https://carbone.io/documentation/developer/api-sdks/javascript.html), [Golang](https://carbone.io/documentation/developer/api-sdks/go.html), [PHP](https://carbone.io/documentation/developer/api-sdks/php.html), [Python](https://carbone.io/documentation/developer/api-sdks/python.html), [Rust](https://carbone.io/documentation/developer/api-sdks/rust.html), and [Java](https://carbone.io/documentation/developer/api-sdks/java.html).
    - Integrations: [Bubble](https://bubble.io/plugin/report-generator---carboneio-1643965604424x905182936531206100), [Make](https://www.make.com/en/integrations/carbone), [Zapier](https://zapier.com/apps/carboneio/integrations), [N8N](github.com/carboneio/n8n-nodes-carbone), Salesforce and Hubspot (Coming soon)
  version: "V5 Beta 18"
  title: "Carbone API"
  contact:
    name: "Carbone Support"
    email: "support@carbone.io"
    url: "https://help.carbone.io"
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://api.carbone.io
tags:
- name: "Document"
  description: "Generate Documents"
- name: "Template"
  description: "Manage Templates"
- name: "Status"
  description : "API Status"
paths:
  /template:
    post:
      tags:
      - "Template"
      summary: "Upload a template."
      description: |
        Uploads a new template to the Carbone storage, supporting optional metadata and advanced features like template versioning. When versioning is enabled, multiple versions of a template can be managed under the same template `id`, and specific versions can be deployed using the `deployedAt` parameter.

        ### Features
        - Metadata Support: Attach metadata such as name, comment, and tags to the template for better organization and retrieval.
        - Template Versioning: By enabling the `versioning` parameter, users can manage multiple versions of a template, allowing for a history of changes and rollbacks.
        - Deployed Version Control: Specify which version of a template is deployed using the `deployedAt` timestamp.
        - Sample Data: Attach sample input data to templates to facilitate testing and development in the Carbone Studio environment.
        
        ### Backward Compatibility
        For backward compatibility, if the `versioning` parameter is not provided or is set to false, the endpoint behaves as it did in previous versions. This means it does not enable the new versioning features and maintains the returned body request `{ "success": true, "data": { "templateId": "SHA256" }}` that older applications expect.
        
        ### Use Cases
        Ideal for template management, including maintaining multiple versions of a document template, automating document generation workflows with precise control over deployments, and enhancing template metadata for better search and retrieval.
      externalDocs:
        url: "https://carbone.io/documentation/developer/http-api/manage-templates.html#upload-a-template"
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/carboneVersion'
      requestBody:
        required: true
        description: "Template file and metadata to upload. The template can be provided either as base64-encoded string or as multipart/form-data. It is important to ensure that the 'template' field is the last element in the request body."
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - "template"
              properties:
                id:
                  type: string
                  description: "Template ID. Generated if not provided and versioning is true."
                  example: ""
                versioning:
                  type: boolean
                  description: "Enables new V5 versioning mode. The versioning is disabled if the attributed undefined or false, and if 'id' is undefined."
                template:
                  type: string
                  format: binary
                  description: "Template File, supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, XHTML, IDML, HTML or an XML file"
                name:
                  type: string
                  description: "Template name."
                comment:
                  type: string
                  description: "Template comment."
                tags:
                  type: array
                  items:
                    type: string
                  description: "List of tags."
                  example: ["invoice", "contract", "v2"]
                samples:
                  type: array
                  items:
                    type: object
                  description: "Sample input data."
                expireAt:
                  type: integer
                  description: "UTC Unix timestamp; values ≥ 42000000000 (year 3300) are interpreted as 'NOW'. 0 means it never expires."
                deployedAt:
                  type: integer
                  description: "UTC Unix timestamp; values ≥ 42000000000 (year 3300) are interpreted as 'NOW'. Future values are not allowed."
          application/json:
            schema:
              type: object
              required:
              - "template"
              properties:
                id:
                  type: string
                  description: "Template ID. Generated if not provided and versioning is true."
                  example: ""
                versioning:
                  type: boolean
                  description: "Enables new versioning mode. Disabled if undefined or false, and if 'id' is undefined."
                template:
                  type: string
                  example: "Base64-encoded Template File contents, supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, XHTML, IDML, HTML or an XML file"
                name:
                  type: string
                  description: "Template name."
                comment:
                  type: string
                  description: "Template comment."
                tags:
                  type: array
                  items:
                    type: string
                  description: "List of tags."
                  example: ["invoice", "contract", "v2"]
                samples:
                  type: array
                  items:
                    type: object
                  description: "Sample input data."
                  example: [{ "id": "42", "name": "John Doe", "type": "invoice"}]
                expireAt:
                  type: integer
                  description: "UTC Unix timestamp; values ≥ 42000000000 (year 3300) are interpreted as 'NOW'. 0 means it never expires."
                deployedAt:
                  type: integer
                  description: "UTC Unix timestamp; values ≥ 42000000000 (year 3300) are interpreted as 'NOW'. Future values are not allowed."
                  
      responses:
        '200':    # status code
          description: On success, returns metadata about the uploaded template. When versioning is enabled, it returns a comprehensive object containing identifiers (`id` and `versionId`), file type, size, and creation timestamp. For backward compatibility (versioning disabled or undefined), it returns only the field "templateId", SHA-256 hash of the template file.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    oneOf:
                      - type: object
                        properties:
                          id:
                            type: string
                            description: "Template ID."
                          versionId:
                            type: string
                            description: "Version ID of the template."
                          type:
                            type: string
                            description: "Type of the template file."
                          size:
                            type: integer
                            description: "Size of the template file in bytes."
                          createdAt:
                            type: integer
                            description: "UTC Unix timestamp of when the template was created."
                      - type: object
                        properties:
                          templateId:
                            type: string
                            description: "SHA-256 hash of the template file (for backward compatibility)."
        '400':
          $ref: '#/components/responses/NotFileError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '415':
          $ref: '#/components/responses/TemplateFormatError'
        '422':
          $ref: '#/components/responses/MissingTemplateFieldError'
  /template/{templateId-or-versionId}:
    patch:
      tags:
      - "Template"
      summary: "Update template metadata."
      description: |
        Updates specific metadata and attributes of an existing template identified by its ID. This endpoint is crucial for managing the lifecycle and details of templates without the need to re-upload the template file. It allows for precise control over template metadata, versioning, and deployment states.

        ### Features
        - Metadata Management: Modify template metadata such as name, comment, and tags for improved organization and searchability.
        - Version Deployment: Update the `deployedAt` field to control which version of a template is actively deployed, ensuring that the correct template version is used in document generation processes.
        - Lifecycle Control: Manage the template's lifecycle by updating the expiration timestamp, allowing for fine-grained control over template availability.

        ### Use Cases
        Updating template metadata to reflect changes in document usage or categorization, switching between template versions for deployment to support different document generation needs, and managing template lifecycle by setting expiration dates to automatically retire outdated templates.
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/templateIdOrVersionId'
        - $ref: '#/components/parameters/carboneVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                comment:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
                expireAt:
                  type: string
                  format: date-time
                deployedAt:
                  type: string
                  format: date-time
      responses:
        '200':
          description: "Template metadata updated successfully."
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '400':
          $ref: '#/components/responses/templateIdNotValidError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/TemplateNotFoundError'
    get:
      tags:
      - "Template"
      summary: "Download a template or a specific version."
      description: |
        Fetches a specific template or version of a template from the Carbone storage. It supports retrieving the latest deployed version of a template using the `templateId`, as well as individual versions via `versionId`. This endpoint also allows downloading JSON data samples associated with templates or specific versions, which are used in the Studio for testing and development purposes.

        ### Features
        - Template Retrieval: Downloads the template file or its associated JSON sample based on the provided ID.
        - Version Specificity: Retrieve specific versions of a template using `versionId`, or fetch the latest deployed template using `templateId`.
        - Data Samples: Access data samples stored with templates or versions, which are useful for testing and development in the Carbone Studio environment.

        ### Parameters
        The `id` of the template or version to download, can also be specified as `{templateId}_sample.json` or `{versionId}_sample.json` to download associated data samples.
        
        ### Use Cases
        Ideal for accessing templates and their associated data samples for testing, integration, or deployment purposes. Supports scenarios requiring version-specific template retrieval or the latest deployed template versions.
      externalDocs:
        url: "https://carbone.io/documentation/developer/http-api/manage-templates.html#download-a-template"
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/templateIdOrVersionId'
        - $ref: '#/components/parameters/carboneVersion'
      responses:
        '200':
          description: "Stream of the file content"
          headers:
            content-disposition:
              schema:
                type: string
              description: "Template name, for instance: 'filename=\"{templateid}.docx\"'."
            content-type:
              schema:
                type: string
              description: "File type"
        '400':
          $ref: '#/components/responses/templateIdNotValidError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/TemplateNotFoundError'
    delete:
      summary: "Delete a template or a specific version."
      description: |
        Removes a specific template or a specific version of a template from the Carbone storage. This endpoint accepts both the `templateId` and `versionId`, enabling precise control over which templates or versions are deleted.

        ### Features
        - Template and Version Deletion: Deletes either the entire template, including all its versions, when using a `templateId`, or a specific version of a template when using a `versionId`.
        - Soft Deletion Mechanism: The deletion process involves setting an `expireAt` timestamp, marking the template for garbage collection after a predefined delay (default: 24 hours). This approach is equivalent to calling `PATCH /template/{id}` with `expireAt = NOW`.
        - Bulk Version Deletion: When a `templateId` is specified, all versions of the template are marked for deletion unless otherwise specified.

        ### Parameters
        The ID of the template or version to delete. This can be a `templateId` to delete an entire template and its versions, or a `versionId` to delete a specific version.
        
        ### Use Case
        Ideal for managing the lifecycle of templates, such as cleaning up outdated versions, removing obsolete templates, or archiving specific versions while maintaining the overall template integrity.
      externalDocs:
        url: "https://carbone.io/documentation/developer/http-api/manage-templates.html#delete-a-template"
      tags:
      - "Template"
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/templateIdOrVersionId'
        - $ref: '#/components/parameters/carboneVersion'
      responses:
        '200':
          description: "The template is deleted"
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    default: true
        '400':
          $ref: '#/components/responses/templateIdNotValidError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/TemplateNotFoundError'
  /templates:
    get:
      tags:
      - "Template"
      summary: "List all templates."
      description: |
        Retrieves a list of templates from the Carbone storage; with comprehensive filtering, searching, and pagination capabilities. By default, the endpoint returns all deployed templates, sorted by creation date in descending order, excluding any that have expired. It supports filtering by various criteria such as template ID, version ID, and category, offering flexibility to retrieve specific subsets of templates. Additionally, it supports fuzzy search in template names and exact matches on IDs and version IDs, enhancing discoverability.

        ### Features
        - Filtering: Filter templates by ID, version ID, and category to narrow down results based on specific criteria.
        - Search Support: Utilize fuzzy search for template names and exact matches for IDs and version IDs to quickly locate desired templates.
        - Version Inclusion: Include all versions of a template in the results by setting the `includeVersions` parameter to true, allowing for comprehensive version tracking.
        - Pagination: Employ cursor-based pagination to efficiently navigate through large datasets, enabling scalable data retrieval.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          description: "Filter by template ID."
          required: false
          schema:
            type: string
        - name: versionId
          in: query
          description: "Filter by version ID."
          required: false
          schema:
            type: string
        - name: category
          in: query
          description: "Filter by category."
          required: false
          schema:
            type: string
        - name: includeVersions
          in: query
          description: "By default equals to false. Use true to list all versions for a specific template ID."
          required: false
          schema:
            type: boolean
            default: false
        - name: search
          in: query
          description: "Search in template name (fuzzy search), version ID (exact match), or template ID (exact match)."
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: "Limit the number of items (100 by default)."
          required: false
          schema:
            type: integer
        - name: cursor
          in: query
          description: "A cursor to use in pagination. The cursor defines your place in the list for fetching the next set of results."
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/carboneVersion'
      responses:
        '200':
          description: "List of deployed templates and their versions."
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    templateId:
                      type: string
                    versionId:
                      type: string
                    name:
                      type: string
                    comment:
                      type: string
                    tags:
                      type: array
                      items:
                        type: string
                    expireAt:
                      type: string
                      format: date-time
                    deployedAt:
                      type: string
                      format: date-time
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /templates/categories:
    get:
      tags:
      - "Template"
      summary: "List all categories used in templates"
      description: "Retrieve a list of all categories used in templates."
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/carboneVersion'
      responses:
        '200':
          description: "List of categories used in templates."
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /templates/tags:
    get:
      tags:
      - "Template"
      summary: "List all tags used in templates"
      description: "Retrieve a list of all tags used in templates."
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/carboneVersion'
      responses:
        '200':
          description: "List of tags used in templates."
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /render/{templateId-or-versionId}:
    post:
      summary: "Generate a document."
      description: |
        Renders a document by merging a specified template with provided JSON data. This endpoint is central to the document generation process in Carbone, allowing users to dynamically create documents based on customizable templates. It supports both template IDs and version IDs, providing flexibility in selecting which version of a template to use for rendering.
  
        ### Features
        - Dynamic Document Generation: Create documents by merging pre-designed templates with dynamic JSON data, ensuring consistency and customization in generated documents.
        - Version Support: Utilize either a template ID or a specific version ID to control which version of a template is used for rendering, allowing for precise document generation.
        - Output Format Flexibility: Generate documents in various formats by specifying output types, catering to diverse business and compliance needs.

        ### Tips
        Use the `download=true` query parameter to generate and download a document in one call. This bypasses the need to call GET `/render/{renderId}` to download the generated document, as the document is not stored in Carbone Storage but returned directly as a stream.
      externalDocs:
        url: "https://carbone.io/documentation/developer/http-api/generate-reports.html"
      security:
        - bearerAuth: []
      tags:
      - "Document"
      parameters:
        - $ref: '#/components/parameters/templateIdOrVersionId'
        - $ref: '#/components/parameters/carboneVersion'
        - name: download
          in: query
          description: "Download the generated document directly"
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: object
                  example: { "id": "42", "name": "John", "type": "invoice" }
                  description: "Required - JSON data-set merged into the template to generate a document"
                convertTo:
                  type: string
                  example: "pdf"
                  description: "Optional - Convert the document into another format. Accepted values: ods xlsx xls csv pdf txt odp ppt pptx jpg png odt doc docx txt jpg png epub html xml idml. List of supported formats: https://carbone.io/documentation.html#supported-files-and-features-list"
                template:
                  type: string
                  description: "Optional - Upload a template in base64 format. When used, the URL should be /render/template."
                  example: "base64-encoded-template"
                timezone:
                  type: string
                  example: "Europe/Paris"
                  description: "Optional - Convert document dates to a timezone. The default timezone is `Europe/Paris`. The date must be chained with the `:formatD` formatter, for instance `{d.date:formatD(YYYY-MM-DD HH:MM)}`. List of accepted timezones (Column TZ identifier): https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"
                lang:
                  type: string
                  example: "fr-fr"
                  description: "Optional - Locale of the generated document, it will be used for translation `{t()}`, formatting numbers with `:formatN`, and currencies `:formatC`. List of supported locales: https://github.com/carboneio/carbone/blob/master/formatters/_locale.js"
                complement:
                  type: object
                  example: {}
                  description: "Optional - Object|Array, extra data accessible in the template with {c.} instead of {d.}"
                variableStr:
                  type: string
                  example: "{#def = d.id}"
                  description: "Optional - Predefine alias, related documentation: https://carbone.io/documentation.html#alias"
                reportName:
                  type: string
                  example: "{d.date}.odt"
                  description: "Optional - Static or dynamic file name returned on the `content-disposition` header when the generated report is fetched with `GET /report/:renderId`. Multiple Carbone tags are accepted, such as `{d.type}-{d.date}.pdf`"
                enum:
                  type: object
                  example: {}
                  description: "Optional - List of enumerations, use it in reports with `convEnum` formatters, documentation: https://carbone.io/documentation.html#convenum-type-"
                translations:
                  type: object
                  example: { "fr": { "one": "un" }, "es": { "one": "uno" } }
                  description: "Optional - When the report is generated, all text between `{t( )}` is replaced with the corresponding translation. The `lang` option is required to select the correct translation. Learn more: https://carbone.io/documentation.html#translations"
                currencySource:
                  type: string
                  example: "EUR"
                  description: "Optional - Currency source coming from your JSON data. The option is used by `formatC` to convert the currency based on the `currencyTarget` and `currencyRates`. Learn more: https://carbone.io/documentation.html#formatc-precisionorformat-"
                currencyTarget:
                  type: string
                  example: "USD"
                  description: "Optional - Target currency when the document is generated. The option is used by `formatC` to convert the currency based on the `currencySource` and `currencyRates`. Learn more: https://carbone.io/documentation.html#formatc-precisionorformat-"
                currencyRates:
                  type: object
                  example: { "EUR": 1, "USD": 1.2 }
                  description: "Optional - Currency exchange rates for conversions from `currencySource` to `currencyTarget`. Learn more: https://carbone.io/documentation.html#formatc-precisionorformat-"
                hardRefresh:
                  type: boolean
                  example: false
                  description: "Optional - If true, the report content is refreshed at the end of the rendering process. To use this option, `convertTo` has to be defined. It is mostly used to refresh a table of content."
                batchSplitBy:
                  type: string
                  description: "Optional - Generate multiple reports by splitting the data array."
                  example: "d.items"
                batchOutput:
                  type: string
                  description: "Optional - Output format for batch processing"
                  example: "zip"
      responses:
        "200":
          description: "On success, by default a JSON response with content-type `application/json` containing the `render ID` is returned, which is a unique identifier for the generated document. If the query parameter `download=true` is used, the response body will be the file itself, and the content type will reflect the type of the generated document."
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    default: true
                  data:
                    type: object
                    properties:
                      renderId:
                        type: string
            # Document Formats
            application/pdf:
              schema:
                type: string
                format: binary
            application/xml:
              schema:
                type: string
                format: binary
            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
              schema:
                type: string
                format: binary
            application/vnd.oasis.opendocument.text:
              schema:
                type: string
                format: binary
            application/epub+zip:
              schema:
                type: string
                format: binary
            text/plain:
              schema:
                type: string
                format: binary
            text/html:
              schema:
                type: string
                format: binary
            application/x-latex:
              schema:
                type: string
                format: binary
            text/x-bibtex:
              schema:
                type: string
                format: binary
            text/x-tex:
              schema:
                type: string
                format: binary
            # Spreadsheet Formats
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
            application/vnd.oasis.opendocument.spreadsheet:
              schema:
                type: string
                format: binary
            text/csv:
              schema:
                type: string
                format: binary
            application/dbf:
              schema:
                type: string
                format: binary
            text/dif:
              schema:
                type: string
                format: binary
            # Presentation Formats
            application/vnd.openxmlformats-officedocument.presentationml.presentation:
              schema:
                type: string
                format: binary
            application/vnd.oasis.opendocument.presentation:
              schema:
                type: string
                format: binary
            image/bmp:
              schema:
                type: string
                format: binary
            image/x-emf:
              schema:
                type: string
                format: binary
            application/postscript:
              schema:
                type: string
                format: binary
            image/gif:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            image/tiff:
              schema:
                type: string
                format: binary
            application/vnd.oasis.opendocument.graphics:
              schema:
                type: string
                format: binary
            image/svg+xml:
              schema:
                type: string
                format: binary
            application/vnd.ms-powerpoint:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/NotJsonError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/TemplateNotFoundError'
        '422':
          $ref: '#/components/responses/MissingDataFieldError'
        '500':
          $ref: '#/components/responses/GenerateReportError'
  /render/{renderId}:
    get:
      summary: "Retrieve a generated document."
      description: |
        Download a  generated document using a unique render ID. This render ID is obtained from a successful call to the `POST /render/{templateId-or-versionId}` endpoint. The retrieved document is provided as a file stream, which can be directly downloaded or viewed.

        ### Features
        - Document Retrieval: Access generated documents using a unique render ID, ensuring secure and direct retrieval.
        - Single-Use Access: The document is deleted immediately after retrieval, ensuring privacy and reducing server storage usage. Subsequent calls with the same render ID will result in a 404 error, as the document is no longer available.

        ### Authentication
        No authentication header is required for this API call, simplifying integration and access for end-users.

      externalDocs:
        url: "https://carbone.io/documentation/developer/http-api/download-reports.html"
      tags:
        - "Document"
      parameters:
        - $ref: '#/components/parameters/renderId'
        - $ref: '#/components/parameters/carboneVersion'
        - name: download
          in: query
          description: "If set to true, changes Content-Disposition to attachment, for direct download."
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: "Stream of the generated document. The content type will correspond to the format of the generated document, which can be any of the supported output file formats."
          content:
            # Document Formats
            application/pdf:
              schema:
                type: string
                format: binary
            application/xml:
              schema:
                type: string
                format: binary
            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
              schema:
                type: string
                format: binary
            application/vnd.oasis.opendocument.text:
              schema:
                type: string
                format: binary
            application/epub+zip:
              schema:
                type: string
                format: binary
            text/plain:
              schema:
                type: string
                format: binary
            text/html:
              schema:
                type: string
                format: binary
            application/x-latex:
              schema:
                type: string
                format: binary
            text/x-bibtex:
              schema:
                type: string
                format: binary
            text/x-tex:
              schema:
                type: string
                format: binary
            # Spreadsheet Formats
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
            application/vnd.oasis.opendocument.spreadsheet:
              schema:
                type: string
                format: binary
            text/csv:
              schema:
                type: string
                format: binary
            application/dbf:
              schema:
                type: string
                format: binary
            text/dif:
              schema:
                type: string
                format: binary
            # Presentation Formats
            application/vnd.openxmlformats-officedocument.presentationml.presentation:
              schema:
                type: string
                format: binary
            application/vnd.oasis.opendocument.presentation:
              schema:
                type: string
                format: binary
            image/bmp:
              schema:
                type: string
                format: binary
            image/x-emf:
              schema:
                type: string
                format: binary
            application/postscript:
              schema:
                type: string
                format: binary
            image/gif:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            image/tiff:
              schema:
                type: string
                format: binary
            application/vnd.oasis.opendocument.graphics:
              schema:
                type: string
                format: binary
            image/svg+xml:
              schema:
                type: string
                format: binary
            application/vnd.ms-powerpoint:
              schema:
                type: string
                format: binary
          headers:
            content-disposition:
              schema:
                type: string
              description: "File name, for instance: 'filename=\"report.pdf\"'. The default value is 'report'. The file name can be changed dynamically thanks to the `reportName` option when generating a document with `POST /render/:templateId`."
            content-type:
              schema:
                type: string
              description: "File type"

        '400':
          $ref: '#/components/responses/RenderIdNotValidError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: "Document not found, typically already retrieved and deleted."
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    default: false
                  error:
                    type: string
                    example: "File not found"
  /status:
    get:
      tags:
      - "Status"
      summary: "Fetch the API status and version"
      responses:
        '200':
          description: "Check the API status and version"
          content:
            application/json:
              schema:
                type: object
                example: { "success": true, "code": 200, "message": "OK", "version": "4.13.0" }
                properties:
                  success:
                    type: boolean
                  code:
                    type: number
                  message:
                    type: string
                  version:
                    type: string
        '500':
          description: "Something went wrong, contact support on the chat"
components:
  securitySchemes:
    bearerAuth:            # arbitrary name for the security scheme
      type: http
      description: "Get you test or production API Key on https://account.carbone.io"
      scheme: bearer
      bearerFormat: "eyJhbGci..."
  parameters:
    carboneVersion:
      name: "carbone-version"
      description: "Carbone version"
      in: "header"
      required: true
      schema:
        type: integer
        format: int32
        default: 5
    templateIdOrVersionId:
      in: path
      name: "templateId-or-versionId"
      description: "Unique identifier of the template or version ID"
      schema:
        type: string
      required: true
    renderId:
      in: path
      name: "renderId"
      description: "Unique identifier of the report"
      schema:
        type: string
      required: true
  responses:
    CResponseError:
      description: Error response when the request is invalid.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                default: false
              data:
                type: object
    UnauthorizedError:
      description: "Unauthorized, please provide a correct API key on the `Authorization ` header. The API key is available on your Carbone account: https://account.carbone.io"
      content:
        application/json:
          schema:
            type: object
            example: { "success" : false, "error" : "Unauthorized, please provide a valid API key on the 'Authorization' header"}
    NotJsonError:
      description: "The body request type is not correct, it must be a JSON type and the `Content-type` header must be `application/json`"
      content:
        application/json:
          schema:
            type: object
            example: { "success" : false, "error" : "'Content-Type' header is not 'application/json'"}
    TemplateNotFoundError:
      description: "The template is not found"
      content:
        application/json:
          schema:
            type: object
            example: { "success" : false, "error" : "Template not found"}
    MissingDataFieldError:
      description: "The 'data' property is missing on the body request."
      content:
        application/json:
          schema:
            type: object
            example: { "success" : false, "error" : "Missing 'data' property in body"}
    GenerateReportError:
      description: "Something went wrong when merging the JSON data-set into the template. The design of the template has an issue."
      content:
        application/json:
          schema:
            type: object
            example: { "success" : false, "error" : "Error while rendering template"}
    NotFileError:
      description: "Bad Request. This error occurs if the template file is not the last field in multipart form-data, if any mandatory field is missing, or if the body request type is not correct; it must be a FormData or a JSON. The Content-type header must be either application/json or multipart/form-data."
      content:
        application/json:
          schema:
            type: object
            example: { "success" : false, "error" : "Content-Type header should be multipart/form-data or application/json, OR, the 'template' field must be the last element in the request body." }
    TemplateFormatError:
      description: "Template format not supported, it must be an XML-based document: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, XHTML, IDML, HTML or an XML file"
      content:
        application/json:
          schema:
            type: object
            example: { "success" : false, "error" : "Template format not supported" }
    MissingTemplateFieldError:
      description: "The `template` field is empty on the body request"
      content:
        application/json:
          schema:
            type: object
            example: { "success" : false, "error" : "'template' field is empty" }
    templateIdNotValidError:
      description: "The `template ID` is not valid"
      content:
        application/json:
          schema:
            type: object
            example: { "success" : false, "error" : "Invalid templateId" }
    FileDoesNotExistError:
      description: "The file does not exist."
      content:
        application/json:
          schema:
            type: object
            example: { "success" : false, "error" : "File not found" }
    RenderIdNotValidError:
      description: "The `render ID` is not valid"
      content:
        application/json:
          schema:
            type: object
            example: { "success" : false, "error" : "Invalid render ID" }
