Documents

Overview

Documents are structured product artifacts generated from recommendations and insights. Supported types: prd (Product Requirements Document), spec (Technical Specification), memo (Decision Memo), user_story, roadmap_update, and release_notes.

Documents follow a review workflow: draft -> review -> approved -> published.

---

Create Document

POST /api/documents

Create a document manually. Requires: Active subscription.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Target workspace
document_type	string	Yes	One of: prd, spec, memo, user_story, roadmap_update, release_notes
title	string	Yes	Document title
content	string	Yes	Markdown content
related_recommendation_id	UUID	No	Linked recommendation
related_insight_ids	UUID[]	No	Linked insight IDs

Response (201 Created)

{
  "id": "e5f6a7b8-c9d0-1234-efab-567890123456",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "document_type": "prd",
  "title": "PRD: Onboarding Wizard Redesign",
  "content": "# Onboarding Wizard Redesign\n\n## Problem Statement\n...",
  "status": "draft",
  "version": 0,
  "created_by": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "created_at": "2026-03-27T14:00:00Z"
}

---

List Documents

GET /api/documents

Query Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
document_type	string	No	Filter by type
status	string	No	Filter by status: draft, review, approved, published
limit	integer	No	Max results (default: 200, max: 500)
offset	integer	No	Pagination offset (default: 0)

Response (200 OK)

{
  "documents": [ ... ],
  "total": 3
}

---

Get Document

GET /api/documents/{document_id}

---

Update Document

PATCH /api/documents/{document_id}

Update a document's content, title, or metadata.

---

Delete Document

DELETE /api/documents/{document_id}

Response (204 No Content)

---

Draft Document (AI)

POST /api/documents/draft

Generate a product document from a recommendation using the AI agent. The agent applies document templates, cites user research throughout, and formats as clean Markdown. Typically takes 20-45 seconds.

Requires: Active subscription.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Target workspace
document_type	string	Yes	Document type to generate
recommendation_id	UUID	No	Recommendation to base the document on
user_instructions	string	No	Additional instructions for the AI

Example Request

curl -X POST https://api.praxiomai.xyz/api/documents/draft \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "document_type": "prd",
    "recommendation_id": "d4e5f6a7-b8c9-0123-defa-456789012345",
    "user_instructions": "Focus on mobile-first experience"
  }'

Response (200 OK)

Returns the generated DocumentResponse with status "draft".

---

Save Version

POST /api/documents/{document_id}/versions

Create a manual version checkpoint of the current document state.

Request Body

Name	Type	Required	Description
change_summary	string	No	Description of changes

Response (201 Created)

{
  "id": "f6a7b8c9-d0e1-2345-fabc-678901234567",
  "document_id": "e5f6a7b8-c9d0-1234-efab-567890123456",
  "revision_number": 3,
  "title": "PRD: Onboarding Wizard Redesign",
  "content": "...",
  "status_at_revision": "draft",
  "change_type": "manual_save",
  "change_summary": "Updated success metrics section",
  "changed_by": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "word_count": 1250
}

---

List Versions

GET /api/documents/{document_id}/versions

List all revisions for a document, newest first.

Query Parameters

Name	Type	Required	Description
limit	integer	No	Max results (default: 50, max: 100)

---

Get Version

GET /api/documents/{document_id}/versions/{revision_id}

Get a specific revision with full content.

---

Diff Versions

GET /api/documents/{document_id}/diff

Compute line-level diff between two revisions.

Query Parameters

Name	Type	Required	Description
from_revision	integer	Yes	Older revision number
to_revision	integer	Yes	Newer revision number

Response (200 OK)

{
  "document_id": "e5f6a7b8-...",
  "from_revision": 1,
  "to_revision": 3,
  "from_content": "...",
  "to_content": "...",
  "diff_stats": {
    "additions": 15,
    "deletions": 3,
    "changes": 18
  }
}

---

Restore Version

POST /api/documents/{document_id}/versions/{revision_id}/restore

Restore document content from a previous revision. Creates revision snapshots before and after the rollback.

Request Body

Name	Type	Required	Description
change_summary	string	No	Reason for restoring

---

Transition Status

POST /api/documents/{document_id}/status

Transition a document through the review workflow.

Request Body

Name	Type	Required	Description
target_status	string	Yes	Target status
change_summary	string	No	Optional notes

Valid Transitions

Current	Valid Next
draft	review
review	approved, draft
approved	published, draft
published	(terminal)

---

Document Blocks

Documents can be decomposed into typed blocks for structured editing in the PM IDE.

List Blocks

GET /api/documents/{document_id}/blocks

Returns all blocks for a document, ordered by position.

Create Block

POST /api/documents/{document_id}/blocks

Name	Type	Required	Description
block_type	string	Yes	One of: problem, persona, solution, metrics, user_story, edge_case, risk, timeline, free_text
title	string	No	Block title
content	object	No	Block content (JSON, structure varies by type)
position	integer	No	Order within the document

Update Block

PATCH /api/documents/{document_id}/blocks/{block_id}

Update a block's title, content, or position.

Delete Block

DELETE /api/documents/{document_id}/blocks/{block_id}

Reorder Blocks

PATCH /api/documents/{document_id}/blocks/reorder

Bulk update block positions.

Extract Blocks from Document

POST /api/blocks/extract

Analyse a document's Markdown content and create typed blocks from its sections.

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
document_id	UUID	Yes	Document to extract blocks from

Parse Intent into Blocks

POST /api/intent/parse

Decompose raw text input into a structured block skeleton.

Name	Type	Required	Description
raw_input	string	Yes	Raw text to parse
workspace_id	UUID	No	Workspace for context

---

Block Actions

AI-powered actions for refining individual blocks.

Expand Block

POST /api/blocks/{block_id}/expand

Flesh out a block with deeper detail using its type-specific contract.

Challenge Block

POST /api/blocks/{block_id}/challenge

Adversarial critique returning strengths, weaknesses, questions, and suggestions.

Simulate Block

POST /api/blocks/{block_id}/simulate

Explore real-world implications of a block's content.