Documents

The Documents API provides structured storage for text artifacts — plans, specs, briefs, templates, and code snippets. Documents are organized by type and category, support tagging, and are searchable by title and content.

Base path: /api/documents

All endpoints require Authorization: Bearer <token>.

---

Document Types

Type	Description
markdown	Markdown-formatted text
code	Source code (any language)
text	Plain text
json	JSON data
yaml	YAML configuration
html	HTML content
css	Stylesheet

Document Categories

Category	Description
planning	Project plans, roadmaps, timelines
specification	Technical specs, API contracts
documentation	User-facing docs, guides
briefing	AI agent briefing files
notes	Informal notes and observations
research	Research findings, competitive analysis
template	Reusable document templates
config	Configuration and environment definitions
other	Anything not covered above

---

List Documents

GET /api/documents

Query parameters:

Parameter	Type	Description
type	string	Filter by document type
category	string	Filter by category
tags	string	Comma-separated tags
search	string	Search in title and content
createdBy	string	Filter by author (agent name or user ID)
limit	number	Default 20, max 100
offset	number	Default 0

Response:

{
  "success": true,
  "data": [
    {
      "id": "doc_01J...",
      "title": "API Route Refactoring Plan",
      "type": "markdown",
      "category": "planning",
      "tags": ["api", "refactoring", "hono"],
      "contentPreview": "# API Route Refactoring Plan\n\nThis document outlines...",
      "createdBy": "architect",
      "createdAt": "2026-04-01T10:00:00Z",
      "updatedAt": "2026-04-03T11:00:00Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 27 }
}

curl:

curl "https://api.cortex.acrobi.com/api/documents?category=planning&type=markdown" \
  -H "Authorization: Bearer <token>"

---

Create Document

POST /api/documents

Request body:

{
  "title": "API Route Refactoring Plan",
  "content": "# API Route Refactoring Plan\n\nThis document outlines the steps to refactor all 32 route handlers...",
  "type": "markdown",
  "category": "planning",
  "tags": ["api", "refactoring", "hono"],
  "projectId": "proj_01J..."
}

Field	Type	Required	Description
title	string	Yes	Document title
content	string	Yes	Full document content
type	string	Yes	Document type (see table above)
category	string	No	Category (default other)
tags	string[]	No	Searchable tags
projectId	string	No	Associate with a project

Response: 201 Created

{
  "success": true,
  "data": {
    "id": "doc_01J...",
    "title": "API Route Refactoring Plan",
    "type": "markdown",
    "category": "planning",
    "createdAt": "2026-04-03T12:00:00Z"
  }
}

curl:

curl -X POST "https://api.cortex.acrobi.com/api/documents" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API Route Refactoring Plan",
    "content": "# Plan\n\nStep 1...",
    "type": "markdown",
    "category": "planning",
    "tags": ["api", "refactoring"]
  }'

---

Get Document

GET /api/documents/:id

Returns full document including content.

Response:

{
  "success": true,
  "data": {
    "id": "doc_01J...",
    "title": "API Route Refactoring Plan",
    "content": "# API Route Refactoring Plan\n\nThis document outlines...",
    "type": "markdown",
    "category": "planning",
    "tags": ["api", "refactoring", "hono"],
    "projectId": "proj_01J...",
    "createdBy": "architect",
    "createdAt": "2026-04-01T10:00:00Z",
    "updatedAt": "2026-04-03T11:00:00Z"
  }
}

---

Update Document

PATCH /api/documents/:id

Request body:

{
  "title": "API Route Refactoring Plan v2",
  "content": "# API Route Refactoring Plan v2\n\nUpdated to reflect Hono middleware approach...",
  "tags": ["api", "refactoring", "hono", "middleware"]
}

Response: 200 OK — returns updated document object.

curl:

curl -X PATCH "https://api.cortex.acrobi.com/api/documents/doc_01J..." \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "API Route Refactoring Plan v2"}'

---

Delete Document

DELETE /api/documents/:id

Permanently removes the document and its content.

Response:

{ "success": true }