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 a management API key (prefix mk_) passed via the Authorization: Bearer header. You can create and manage API keys from your dashboard.

Example request

curl -H "Authorization: Bearer mk_your-api-key-here" \
     https://your-domain.com/api/v1/documents

Available Abilities

documents:readdocuments:writefolders:readfolders:writetags:readtags:writefiles:readfiles:writerag:read

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

Search & RAG

Method	Path	Description	Ability
POST	/search/semantic	Hybrid semantic search; returns chunk-level hits	rag:read
GET	/documents/{id}/chunks/{chunkId}	Fetch a single chunk by id	rag: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 "Authorization: Bearer mk_your-api-key" \
     https://your-domain.com/api/v1/documents

cURL — Get a single document

curl -H "Authorization: Bearer mk_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 "Authorization: Bearer mk_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: { "Authorization": "Bearer mk_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