Skip to main content

​
Endpoints

MethodPathScopeDescription
GET/documentsdocuments:readList documents
POST/documentsdocuments:writeCreate a document
GET/documents/:iddocuments:readGet a document with content
PATCH/documents/:iddocuments:writeUpdate a document
DELETE/documents/:iddocuments:writeSoft-delete a document

​
List Documents

curl "https://my.clarife.app/api/v1/documents?limit=10&offset=0" \
  -H "Authorization: Bearer clrf_your_key"
Query parameters:
ParamTypeDefaultDescription
limitinteger50Results per page (max 100)
offsetinteger0Number of results to skip
project_iduuid—Filter by project
Response: 
{
  "data": [
    {
      "id": "d1a2b3c4-5678-90ab-cdef-1234567890ab",
      "title": "Getting Started Guide",
      "description": "Onboarding tutorial for new users",
      "project_id": null,
      "created_at": "2026-03-15T10:30:00Z",
      "updated_at": "2026-03-20T14:00:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

​
Create a Document

curl -X POST https://my.clarife.app/api/v1/documents \
  -H "Authorization: Bearer clrf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API Setup Guide",
    "description": "How to connect via the clarife API",
    "project_id": "p1a2b3c4-5678-90ab-cdef-1234567890ab"
  }'
Body parameters:
FieldTypeRequiredDescription
titlestringYesDocument title (max 200 chars)
descriptionstringNoShort description (max 500 chars)
contentobjectNoDocument content (see format below)
project_iduuidNoAssign to a project
Response (201 Created): 
{
  "data": {
    "id": "d2b3c4d5-6789-01ab-cdef-2345678901ab",
    "title": "API Setup Guide",
    "description": "How to connect via the clarife API",
    "project_id": "p1a2b3c4-5678-90ab-cdef-1234567890ab",
    "content": null,
    "created_at": "2026-03-28T12:00:00Z",
    "updated_at": "2026-03-28T12:00:00Z"
  }
}

​
Get a Document

curl https://my.clarife.app/api/v1/documents/d1a2b3c4-5678-90ab-cdef-1234567890ab \
  -H "Authorization: Bearer clrf_your_key"
Returns the full document including content.

​
Update a Document

curl -X PATCH https://my.clarife.app/api/v1/documents/d1a2b3c4-5678-90ab-cdef-1234567890ab \
  -H "Authorization: Bearer clrf_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated Title" }'
All body fields are optional. Only provided fields are updated.
FieldTypeDescription
titlestringNew title
descriptionstringNew description
contentobjectReplace document content

​
Delete a Document

curl -X DELETE https://my.clarife.app/api/v1/documents/d1a2b3c4-5678-90ab-cdef-1234567890ab \
  -H "Authorization: Bearer clrf_your_key"
Documents are soft-deleted (moved to trash). They are permanently removed after 30 days. Response (200 OK): 
{ "data": { "id": "d1a2b3c4-...", "deleted_at": "2026-03-28T12:00:00Z" } }

​
Content Format

Document content follows a block-based structure: 
{
  "meta": {
    "version": 1,
    "locale": "en"
  },
  "blocks": [
    {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [{ "type": "text", "text": "Step 1" }]
    },
    {
      "type": "text",
      "content": [{ "type": "text", "text": "Click the button to begin." }]
    },
    { "type": "divider" },
    {
      "type": "code",
      "attrs": { "language": "bash" },
      "content": [{ "type": "text", "text": "npm install clarife" }]
    },
    {
      "type": "table",
      "attrs": { "rows": 2, "cols": 2 },
      "content": [["Name", "Value"], ["key", "clrf_xxx"]]
    }
  ]
}
Supported block types: heading, text, code, table, divider
Screenshot blocks are created by uploading media first via the Media API and referencing the returned key in the content.