API Reference: Document Module

This document details the RESTful API endpoints for the Document module.

---

1. Authentication

All requests MUST include a Platform JWT in the Authorization header.

---

2. Document API

GET /documents

List documents in the current organization.

Query Parameters:

• status: Filter by document_status.
• q: Full-text search across titles and content.

POST /documents

Create a new document. Supports creating from a template.

Body:

{
  "title": "New Strategy",
  "templateId": "uuid"
}

GET /documents/:id

Fetch the current published version and metadata.

PUT /documents/:id

Save a new draft version. Only allowed if status is draft.

Body:

{
  "title": "Updated Title",
  "content": { "type": "doc", "content": [...] }
}

---

3. Versioning API

GET /documents/:id/versions

Fetch version history for a document.

POST /documents/:id/versions/:versionId/restore

Promote an old version to the current draft.

---

4. Approval Workflow API

POST /documents/:id/submit-review

Submit document for approval. Changes status to in_review.

Body:

{
  "reviewerId": "shell-user-uuid",
  "comment": "Final draft ready for HR review."
}

POST /approval-requests/:id/decide

Approve or request changes for a document.

Body:

{
  "status": "approved",
  "comment": "Looks good."
}

---

5. Standard Error Codes

Status Code	Description
403 Forbidden	Document is locked for editing (In Review) or lacks permissions.
404 Not Found	Document or version does not exist.
422 Unprocessable Entity	Invalid TipTap JSON structure.
500 Server Error	Unexpected backend failure.