Qualio Documents API

openapi: 3.1.0
info:
  title: Qualio Developer Documents API
  version: '0.1'
  description: "Whether you're streamlining document control, automating quality event management, integrating training records, or syncing supplier data across systems, the Qualio API provides secure and scalable solutions. Getting started is easy: generate an API key, authenticate your requests, explore example code, and start building. Follow the steps below to integrate with Qualio quickly and efficiently.\n\n  This portal includes everything you need to build with confidence:\n- Secure, token-based authentication\n- Full reference documentation for each endpoint\n- Example code in multiple programming languages\n- \"Try it out\" functionality to test requests live\n- Fair usage rate limits to ensure system stability\n \n\n #### Generate Your API Key \n To access the API, you’ll need an API key:\n\n- Log in to the [Qualio admin panel](https://app.qualio.com/user-management/admin).\n\n- Navigate to Admin Settings > [Developer API tokens](https://app.qualio.com/user-management/admin/dev-api).\n\n- Click Create token and save the key securely.\n\n- Only users with administrative privileges can generate API keys. \n\n\n\nIf you don’t have admin access, please ask your Qualio administrator to create a key for you.\n \n\n #### Authenticate Your Requests\n\nQualio uses API key authentication using the X-Api-Key header. Add your API key in the authentication panel to the right to see examples of how to use it in a language of your choice.\n \n\n #### Make Your First API Call\n\nHere is an easy place to get started: [fetching all your effective documents](#tag/documents/GET/v1/documents/query)\n \n\n #### Respect Rate Limits\n\nTo ensure fair use and maintain performance, API requests are subject to rate limits:\n\n- Each API key has a request threshold of maximum 200 requests per minute\n- If you exceed this limit, you'll receive an HTTP 429 (Too Many Requests) response.\n- We recommend implementing retry logic in your client applications, if this is a concern for you.\n\n \n\n #### Explore and Build\nUse the navigation panel to browse available API endpoints, such as:\n- Documents — Create, query, and manage your controlled documents\n- User Management — Invite users, update roles, or sync user data\n- Audit Trail — Retrieve historical changes for compliance reporting\n- You’ll find example code in Python, JavaScript, C#, Ruby, PHP, Go, and Shell for each endpoint. Click “Try it out” to test requests directly from the browser.\n \n\n #### How is this API versioned? \n We prefix each URL with the major version of the API. Within this major version, we promise to not make any breaking changes, which are:\n - Changes to the datatype of request or response payload attribute. \n - Removal of an attribute or parameter. \n - Changes to a URL. \n\n We do not consider the following to be breaking changes: \n - Additional attributes on return payloads  \n - Additional optional attributes on request payloads \n\n \n#### Where can I get an OpenApi spec for this? \n You can [find it here](/download-openapi), but bear in mind that this API is updated regularly, so be sure to fetch it afresh for the latest features\n"
servers:
- url: https://api.qualio.com
security:
- api_key: []
tags:
- name: Documents
paths:
  /v1/documents/document/{documentId}:
    get:
      summary: Retrieve a document
      description: "Retrieves a single document version by its numeric id, with full details including title, status, version, owner, reviewers/approvers, and tags. In Qualio, each version of a document has its own numeric id, while the document code (e.g. SOP-1) is shared across all versions â\x80\x94 this endpoint returns the specific version identified by `documentId`. Use the versions endpoints to list the other versions of the same document."
      operationId: getDocument
      tags:
      - Documents
      security:
      - api_key: []
      parameters:
      - in: path
        name: documentId
        schema:
          $ref: '#/components/schemas/documentId'
        required: true
        description: A unique identifier for a document version
      responses:
        '200':
          description: Successful document retrieval
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/documentDetailed'
        '400':
          description: The request has malformed path parameters
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericBadRequest400PathResponse'
        '403':
          description: This API key is not allowed to perform this action, or the API key is incorrect
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericForbiddenResponse'
        '404':
          description: Document not found
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic404'
        '429':
          description: This API key has exceeded the fair usage policy in Qualio, and has it its requests restricted. This request has not been processed
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/throttledResponse'
    options:
      description: "Retrieves a single document version by its numeric id, with full details including title, status, version, owner, reviewers/approvers, and tags. In Qualio, each version of a document has its own numeric id, while the document code (e.g. SOP-1) is shared across all versions â\x80\x94 this endpoint returns the specific version identified by `documentId`. Use the versions endpoints to list the other versions of the same document."
      operationId: getDocumentOptions
      tags:
      - Documents
      x-scalar-ignore: true
      parameters:
      - in: path
        name: documentId
        schema:
          $ref: '#/components/schemas/documentId'
        required: true
        description: A unique identifier for a document version
      responses:
        '200':
          description: Options 200
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
    patch:
      summary: Update document people and tags
      description: "Updates the approvers, reviewers, and/or tags of a document that is in **draft** status (for approvers and reviewers) or any status (for tags).\n\nThis is a **partial update**: only the fields included in the request body are modified. Omitted fields are left unchanged. Each supplied list fully replaces the current set for that role â\x80\x94 to add a single reviewer, include all existing reviewer IDs plus the new one.\n\n**Quality approvers vs other approvers**: Qualio distinguishes between quality approvers (users belonging to the Quality group) and other approvers. Supply them in separate lists; they are merged and stored together as the document's approver group.\n\n**Errors:**\n- `400` with slug `document_not_in_draft`: approvers or reviewers were supplied but the document is not in draft status.\n- `404`: the document does not exist or is not accessible to the API key's user."
      operationId: updateDocument
      tags:
      - Documents
      security:
      - api_key: []
      parameters:
      - in: path
        name: documentId
        schema:
          $ref: '#/components/schemas/documentId'
        required: true
        description: A unique identifier for a document version
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateDocumentPayload'
      responses:
        '200':
          description: The document with its updated approvers, reviewers, and tags
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/documentDetailed'
        '400':
          description: The request has malformed path parameters
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericBadRequest400PathResponse'
        '403':
          description: This API key is not allowed to perform this action, or the API key is incorrect
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericForbiddenResponse'
        '404':
          description: Document not found
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic404'
        '429':
          description: This API key has exceeded the fair usage policy in Qualio, and has it its requests restricted. This request has not been processed
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/throttledResponse'
  /v1/documents/document/{documentId}/content:
    get:
      summary: Retrieve document content
      description: Retrieves the section content of a specific document version, identified by its numeric id. Content is returned per section (each with a title and HTML body). Use `GET /v1/documents/document/{documentId}` for the document's metadata, or the templates endpoints for the section structure of a document type.
      operationId: getDocumentContent
      tags:
      - Documents
      security:
      - api_key: []
      parameters:
      - in: path
        name: documentId
        schema:
          $ref: '#/components/schemas/documentId'
        required: true
        description: A unique identifier for a document version
      responses:
        '200':
          description: Successful document content retrieval
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/documentContentResponse'
        '400':
          description: The request has malformed path parameters
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericBadRequest400PathResponse'
        '403':
          description: This API key is not allowed to perform this action, or the API key is incorrect
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericForbiddenResponse'
        '404':
          description: Document not found
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic404'
        '429':
          description: This API key has exceeded the fair usage policy in Qualio, and has it its requests restricted. This request has not been processed
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/throttledResponse'
    options:
      description: Retrieves the section content of a specific document version, identified by its numeric id. Content is returned per section (each with a title and HTML body). Use `GET /v1/documents/document/{documentId}` for the document's metadata, or the templates endpoints for the section structure of a document type.
      operationId: getDocumentContentOptions
      tags:
      - Documents
      x-scalar-ignore: true
      parameters:
      - in: path
        name: documentId
        schema:
          $ref: '#/components/schemas/documentId'
        required: true
        description: A unique identifier for a document version
      responses:
        '200':
          description: Options 200
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
    patch:
      summary: Update document content
      description: 'Updates the HTML section content of a document that is in **draft** status.


        This is a **partial update**: only the sections listed in the request body are modified. Sections not included retain their existing content unchanged. To replace all content, include every section position defined by the document template.


        **Sections are identified by their `position` number** (1-indexed, matching the order defined by the document template). Use `GET /v1/documents/templates/{templateId}/content` to discover the positions and titles available for a given template.


        **Content format**: Section content is stored and returned as HTML. Plain text is also accepted. Unsafe HTML is stripped on ingestion, and only a permitted set of tags and attributes is stored.


        **Collaboration sessions**: Any in-progress collaborative editing session on this document is automatically cleared when this endpoint is called, ensuring the content provided here is what gets persisted. Do not call this endpoint while end-users are actively editing the same document in the Qualio UI, as it will discard their unsaved changes.


        **Errors:**

        - `400` with slug `document_not_in_draft`: the document exists but is not in draft status. Only draft documents can have their content updated via this endpoint.

        - `404`: the document does not exist, belongs to a different organisation, or is not accessible to the API key''s user.'
      operationId: updateDocumentContent
      tags:
      - Documents
      security:
      - api_key: []
      parameters:
      - in: path
        name: documentId
        schema:
          $ref: '#/components/schemas/documentId'
        required: true
        description: A unique identifier for a document version
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateDocumentContentPayload'
      responses:
        '200':
          description: The full updated content of the document, including all sections (both modified and unmodified)
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/documentContentResponse'
        '400':
          description: The request has malformed path parameters
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericBadRequest400PathResponse'
        '403':
          description: This API key is not allowed to perform this action, or the API key is incorrect
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericForbiddenResponse'
        '404':
          description: Document not found
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic404'
        '429':
          description: This API key has exceeded the fair usage policy in Qualio, and has it its requests restricted. This request has not been processed
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/throttledResponse'
  /v1/documents/document/{documentId}/status:
    put:
      summary: Change document status
      description: 'Advances or reverts the lifecycle status of a document.


        **The document must be accessible to the API key''s user.** The transition must be valid for the document''s current status. Invalid transitions are rejected with a 400 and the document is left unchanged.


        **Valid status transitions:**


        | From | To | Notes |

        |------|----|-------|

        | `draft` | `for_review` | Document must have at least one reviewer assigned |

        | `draft` | `for_approval` | Document must have at least one approver (including a quality approver) |

        | `for_review` | `for_approval` | Document must have at least one approver |

        | `for_review` | `draft` | Reverts to draft |

        | `for_approval` | `draft` | Reverts to draft |

        | `approval_declined` | `draft` | Reverts to draft after a decline |

        | `deleted` | `draft` | Restores a deleted document to draft |


        Transitions that require electronic signature authentication (such as `for_approval` to `approved`, `approved` to `effective`, and `for_approval` to `approval_declined`) are not supported via this endpoint and will return a 400 with slug `esign_required`.


        **Side effects, same as the Qualio UI:**

        - Notifications are sent to reviewers or approvers on `for_review` and `for_approval` transitions

        - The audit trail records the status change, the acting user, and any comment provided

        - Reverting to `draft` clears any in-progress approvals and notifies affected users


        **Errors:**

        - `400`: the transition is not valid (e.g. no reviewers assigned, document is not in a state that permits the requested transition, or the transition requires e-signature). The error message describes the specific reason.

        - `404`: the document does not exist or is not accessible to the API key''s user.'
      operationId: changeDocumentStatus
      tags:
      - Documents
      security:
      - api_key: []
      parameters:
      - in: path
        name: documentId
        schema:
          $ref: '#/components/schemas/documentId'
        required: true
        description: A unique identifier for a document version
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/changeDocumentStatusPayload'
      responses:
        '200':
          description: The document with its updated status and metadata. Use the returned `status` field to confirm the transition completed.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/documentStatusChangeResponse'
        '400':
          description: The request has malformed path parameters
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericBadRequest400PathResponse'
        '403':
          description: This API key is not allowed to perform this action, or the API key is incorrect
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericForbiddenResponse'
        '404':
          description: Document not found
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic404'
        '429':
          description: This API key has exceeded the fair usage policy in Qualio, and has it its requests restricted. This request has not been processed
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Content-Type:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/throttledResponse'
    options:
      description: 'Advances or reverts the lifecycle status of a document.


        **The document must be accessible to the API key''s user.** The transition must be valid for the document''s current status. Invalid transitions are rejected with a 400 and the document is left unchanged.


        **Valid status transitions:**


        | From | To | Notes |

        |------|----|-------|

        | `draft` | `for_review` | Document must have at least one reviewer assigned |

        | `draft` | `for_approval` | Document must have at least one approver (including a quality approver) |

        | `for_review` | `for_approval` | Document must have at least one approver |

        | `for_review` | `draft` | Reverts to draft |

        | `for_approval` | `draft` | Reverts to draft |

        | `approval_declined` | `draft` | Reverts to draft after a decline |

        | `deleted` | `draft` | Restores a deleted document to draft |


        Transitions that require electronic signature authentication (such as `for_approval` to `approved`, `approved` to `effective`, and `for_approval` to `approval_declined`) are not supported via this endpoint and will return a 400 with slug `esign_required`.


        **Side effects, same as the Qualio UI:**

        - Notifications are sent to reviewers or approvers on `for_review` and `for_approval` transitions

        - The audit trail records the status change, the acting user, and any comment provided

        - Reverting to `draft` clears any in-progress approvals and notifies affected users


        **Errors:**

        - `400`: the transition is not valid (e.g. no reviewers assigned, document is not in a state that permits the requested transition, or the transition requires e-signature). The error message describes the s

# --- truncated at 32 KB (113 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/qualio/refs/heads/main/openapi/qualio-documents-api-openapi.yml