v1 — Read & Write

API Reference

Access your MarkNest documents, folders, tags, and files programmatically. Integrate your content into any workflow with our REST API.

Authentication

All API requests require an API key passed via the X-API-Key header. You can create and manage API keys from your dashboard.

Example request

curl -H "X-API-Key: your-api-key-here" \
     https://your-domain.com/api/v1/documents

Available Abilities

documents:readdocuments:writefolders:readfolders:writetags:readtags:writefiles:readfiles:write

Endpoints

View full reference →

Documents

Method	Path	Description	Ability
GET	/documents	List all documents	documents:read
POST	/documents	Create a document	documents:write
GET	/documents/{id}	Get a single document	documents:read
PUT	/documents/{id}	Update a document	documents:write
DELETE	/documents/{id}	Delete a document	documents:write
GET	/documents/{id}/versions	List version history	documents:read
GET	/documents/{id}/versions/{versionId}	Get a specific version	documents:read

Folders

Method	Path	Description	Ability
GET	/folders	List all folders	folders:read
POST	/folders	Create a folder	folders:write
GET	/folders/{id}	Get a single folder	folders:read
PUT	/folders/{id}	Update a folder	folders:write
DELETE	/folders/{id}	Delete a folder	folders:write
GET	/folders/{id}/documents	List documents in a folder	folders:read

Method	Path	Description	Ability
GET	/tags	List all tags	tags:read
POST	/tags	Create a tag	tags:write
PUT	/tags/{id}	Update a tag	tags:write
DELETE	/tags/{id}	Delete a tag	tags:write
GET	/tags/{id}/documents	List documents with a tag	tags:read

Files

Method	Path	Description	Ability
GET	/files	List all uploaded files	files:read
POST	/files	Upload files	files:write
GET	/files/{id}	Get file metadata	files:read
PUT	/files/{id}	Update file metadata	files:write
DELETE	/files/{id}	Delete a file	files:write
GET	/files/{id}/download	Download a file	files:read
GET	/files/{id}/serve	Serve a file inline	files:read

Interactive

Browse the full API reference

Every endpoint, parameter, request body, and response schema — generated directly from the backend OpenAPI specification.

Open Reference →

Code Examples

cURL — List documents

curl -H "X-API-Key: your-api-key" \
     https://your-domain.com/api/v1/documents

cURL — Get a single document

curl -H "X-API-Key: your-api-key" \
     https://your-domain.com/api/v1/documents/42

cURL — Create a document

curl -X POST https://your-domain.com/api/v1/documents \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title":"Meeting notes","content":"# Summary","status":"draft"}'

JavaScript — List documents

const res = await fetch("https://your-domain.com/api/v1/documents", {
  headers: { "X-API-Key": "your-api-key" },
});
const data = await res.json();
console.log(data);

Response Format

Success response (single resource)

{
  "data": {
    "id": 42,
    "title": "My Document",
    "content": "# Hello World",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-20T14:00:00Z"
  }
}

Success response (collection)

{
  "data": [
    { "id": 1, "title": "First Document" },
    { "id": 2, "title": "Second Document" }
  ],
  "meta": { "current_page": 1, "last_page": 3, "per_page": 15, "total": 42 }
}

Error response

{
  "message": "Unauthenticated."
}

Status Codes

Code	Meaning
200	Success
401	Missing or invalid API key
403	API key lacks required ability
404	Resource not found
429	Rate limit exceeded

← Back to Home