API

HTTP endpoints for integrating Clarity into your app. JSON in, JSON out.

Endpoints

POST /v1/refine – refine text with Structure Coach
POST /v1/score – compute clarity score for a draft
POST /v1/summarize – summarize or outline a draft
POST /v1/plugins/run – execute a plugin in sandbox

Request

POST https://api.clarity.app/v1/refine
Authorization: Bearer CLARITY_API_KEY
Content-Type: application/json

{
  "text": "We should restructure the proposal by…",
  "tone": "professional",
  "hints": ["lead with purpose", "shorten intro"]
}

Response

200 OK
{
  "refined": "Start by stating the goal in one line...",
  "sections": [
    {"name": "Purpose", "suggestion": "State outcome first"},
    {"name": "Context", "suggestion": "Remove repeated details"}
  ],
  "score": {"clarity": 72, "readability": 78, "structure": 68},
  "latency_ms": 412
}

Authentication

Send your API key via Bearer token in the Authorization header.