Clarity

Public v1 API

These routes are accessible to developer API tokens issued from the developer portal. All public routes are under the /v1/ prefix. Requests to any route without this prefix are rejected with 403 when authenticated with a developer token.

Route	Scope required	Description
GET /v1/documents	documents:list	List the authenticated user's documents
GET /v1/documents/{id}	documents:read	Read document metadata and body
GET /v1/marketplace	—	List live marketplace plugins (no token required)
POST /v1/marketplace/install/{id}	—	Install a marketplace plugin for the current user
POST /v1/ai/delegate-check	—	Run an AI check billed to the user's token allowance (marketplace plugins only)

The API is versioned at the path level. Breaking changes require a new version. Clarity maintains a deprecated version for at least 90 days after a successor is available.

Developer API Tokens

Developer tokens authenticate calls to the public /v1/ routes. They are issued from the developer portal and are distinct from user session cookies.

Tied to the developer account, not to a specific user.
Carry a fixed scope set chosen at creation time. A token can be scoped down but not up after creation.
Rate-limited to 120 requests/minute per token by default.
Every call is logged with timestamp, route, plugin id, and response status.
The token value is shown only once at creation. If lost, generate a new one.
Revocable at any time; revocation takes effect within 60 seconds.

GET /v1/documents
Authorization: Bearer clr_dev_xxxxxxxxxxxxxxxxxxxx

Calls made with developer tokens are billed to the developer's own token balance, not the user's.

AI Check

POST /v1/ai/check
Authorization: Bearer clr_dev_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "action": "check",
  "document_text": "Draft text..."
}

200 OK
X-Clarity-Tokens-Remaining: 4820

{
  "action": "check",
  "result": {
    "title": "Writing Check",
    "summary": "Short summary",
    "content": "Detailed feedback",
    "score": 78,
    "suggestions": [
      "Lead with the main claim.",
      "Tighten the second paragraph."
    ]
  }
}

The remaining balance is returned in X-Clarity-Tokens-Remaining on every AI response. When the balance is exhausted the route returns 429 with a resets_at timestamp.

User Token Delegation

The delegation route lets a marketplace plugin run an AI check billed against the user's own allowance instead of the developer's — for cases where the user is directly triggering the action from within the editor.

POST /v1/ai/delegate-check
Cookie: clarity_access=<http-only session cookie>
Content-Type: application/json

{
  "action": "check",
  "document_text": "...",
  "plugin_id": "marketplace-plugin-uuid"
}

Restricted: the plugin must be marketplace-approved, the user must have it installed and enabled, and the call must come from an active browser session — not a server-side call. Every delegation call is logged per-user and visible from the user's settings page.

Versioning

The public API is versioned at the path level (/v1/...). Breaking changes require a new version prefix. Clarity commits to maintaining a deprecated version for a minimum of 90 days after a successor version is available.