Document Versions API — Create Versions and Approve

QualityDocD documents use semantic versioning with a major.minor format. Each version lives in one of three states: draft (newly created, not yet active), current (the single active version at any moment), or obsolete (superseded by a newer approval). Creating a new version always yields a draft; promoting it to current is a separate approval step that automatically retires the previous current version, tokenizes the document content into the PostgreSQL search index, and asynchronously pushes metadata to MongoDB. Both endpoints in this group require MODULE_1 access — meaning OPERATOR, COMPANY_ADMIN, or SUPER_ADMIN roles.

POST /documents/:id/versions

Creates a new draft version for an existing document. The version number is calculated automatically from the document’s existing version history. Only users with MODULE_1 access may create new versions. Auth: Bearer token
Module access: MODULE_1 — OPERATOR, COMPANY_ADMIN, SUPER_ADMIN

Path parameters

integer

required

The ID of the document to add a new version to.

Request body

contentText

string

required

Plain-text content for this version. Stored in the database and used for search indexing when the version is approved.

contentUrl

string | null

Optional URL to the document file (e.g. a cloud storage link). May be omitted or null.

bumpMajor

boolean

Controls whether the major or minor version component is incremented. Defaults to false.

false — bumps the minor version: 1.3 → 1.4
true — bumps the major version and resets minor to 0: 1.3 → 2.0

Version numbering logic

The API inspects all existing versions for the document to determine the next version number:

Finds the highest majorVersion across all existing versions.
Among all versions sharing that major number, finds the highest minorVersion.
If bumpMajor is true, sets newMajor = latestMajor + 1 and newMinor = 0.
Otherwise, sets newMajor = latestMajor and newMinor = latestMinor + 1.

curl -X POST https://api.qualitydocd.example/api/documents/12/versions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "contentText": "Política de calidad v2 — revisada tras auditoría externa",
    "contentUrl": "https://storage.example.com/docs/manual-v2.pdf",
    "bumpMajor": true
  }'

Response `201`

Returns the newly created version object. Its status is always "draft".

integer

Unique identifier for this version.

documentId

integer

ID of the parent document.

companyId

integer

Company the version belongs to.

majorVersion

integer

Major component of the version number.

minorVersion

integer

Minor component of the version number.

versionNumber

string

Human-readable version string, e.g. "2.0" or "1.4".

status

"draft"

Always "draft" for a freshly created version.

contentUrl

string | null

The URL provided in the request body, or null.

contentText

string

The plain-text content provided in the request body.

createdBy

integer

User ID of the user who created this version.

approvedBy

integer | null

Always null for a freshly created draft version.

approvedAt

string | null

Always null for a freshly created draft version.

createdAt

string (ISO 8601)

Timestamp of when this version record was created.

{
  "id": 22,
  "documentId": 12,
  "companyId": 3,
  "majorVersion": 2,
  "minorVersion": 0,
  "versionNumber": "2.0",
  "status": "draft",
  "contentUrl": "https://storage.example.com/docs/manual-v2.pdf",
  "contentText": "Política de calidad v2 — revisada tras auditoría externa",
  "createdBy": 7,
  "approvedBy": null,
  "approvedAt": null,
  "createdAt": "2025-03-01T09:00:00.000Z"
}

Error responses

Status	Body	Cause
`400`	`{ "error": "..." }`	Request body failed validation
`404`	`{ "error": "Document not found" }`	No document with that ID exists in the user’s company

POST /documents/:id/versions/:versionId/approve

Promotes a draft version to "current", retiring any previously current version as "obsolete". This endpoint performs four distinct actions in sequence and then triggers an asynchronous MongoDB sync before returning. Auth: Bearer token
Module access: MODULE_1 with write flag — OPERATOR, COMPANY_ADMIN, SUPER_ADMIN

Path parameters

integer

required

The ID of the parent document.

versionId

integer

required

The ID of the version to approve. Must belong to the document specified by id and to the authenticated user’s company.

curl -X POST https://api.qualitydocd.example/api/documents/12/versions/22/approve \
  -H "Authorization: Bearer <token>"

Approval flow

Retire existing current version

All versions of this document that currently have status="current" are updated to status="obsolete". This ensures only one version is ever current at a time.

Promote the target version

The target version is updated: status is set to "current", approvedBy is set to the authenticated user’s ID, and approvedAt is set to the current UTC timestamp.

Tokenize and index in PostgreSQL

The version’s versionNumber is tokenized into titleTokens, and the version’s contentText is tokenized into bodyTokens. Both are deduplicated and merged into a combined tokens array. If no existing search_index row exists for this version, these arrays are inserted into the search_index table, enabling fast fallback full-text search if MongoDB is unavailable. If a row already exists, the index is left unchanged.

Async MongoDB upsert

Document metadata is pushed to the document_metadata MongoDB collection using updateOne with upsert: true. This operation runs in the background and does not block the HTTP response. If it fails, a warning is logged but the approval result is still returned successfully.

MongoDB sync fields

When the async upsert runs, the following fields are written to the document_metadata collection:

Field	Value
`documentId`	Parent document ID
`versionId`	Approved version ID
`companyId`	Company ID
`title`	Document title
`format`	Document format (e.g. `"pdf"`)
`version`	Version number string (e.g. `"2.0"`)
`status`	Always `"Approved"`
`contentText`	Plain-text content of the version
`tags`	Array of lowercase words derived from the document title
`approvedAt`	UTC timestamp of approval

MongoDB sync failures are caught silently and logged as warnings. The approval response is always returned once the PostgreSQL steps complete, regardless of whether the MongoDB upsert succeeds.

Response `200`

Returns the updated version object reflecting its new approved state.

integer

Version ID.

documentId

integer

Parent document ID.

companyId

integer

Company ID.

majorVersion

integer

Major version component.

minorVersion

integer

Minor version component.

versionNumber

string

Human-readable version string.

status

"current"

Always "current" after a successful approval.

contentUrl

string | null

URL to the document file, if one was provided.

contentText

string | null

Plain-text content of the version.

createdBy

integer

User ID who created this version.

approvedBy

integer

User ID who approved this version.

approvedAt

string (ISO 8601)

Timestamp of approval.

{
  "id": 22,
  "documentId": 12,
  "companyId": 3,
  "majorVersion": 2,
  "minorVersion": 0,
  "versionNumber": "2.0",
  "status": "current",
  "contentUrl": "https://storage.example.com/docs/manual-v2.pdf",
  "contentText": "Política de calidad v2 — revisada tras auditoría externa",
  "createdBy": 7,
  "approvedBy": 9,
  "approvedAt": "2025-03-05T10:30:00.000Z"
}

Error responses

Status	Body	Cause
`403`	`{ "error": "Acceso denegado al MODULE_1" }`	User lacks MODULE_1 write access
`404`	`{ "error": "Version not found" }`	No version with that ID exists for the given document in the user’s company

Authentication

Documents

Platform

Document Versions API — Create Versions and Approve

POST /documents/:id/versions

Path parameters

Request body

Version numbering logic

Response `201`

Error responses

POST /documents/:id/versions/:versionId/approve

Path parameters

Approval flow

MongoDB sync fields

Response `200`

Error responses

Build docs developers (and LLMs) love

Authentication

Documents

Platform

Documentation Index

​POST /documents/:id/versions

​Path parameters

​Request body

​Version numbering logic

​Response 201

​Error responses

​POST /documents/:id/versions/:versionId/approve

​Path parameters

​Approval flow

​MongoDB sync fields

​Response 200

​Error responses

Build docs developers (and LLMs) love

POST /documents/:id/versions

Path parameters

Request body

Version numbering logic

Response `201`

Error responses

POST /documents/:id/versions/:versionId/approve

Path parameters

Approval flow

MongoDB sync fields

Response `200`

Error responses