Sandbox API — Clarity Developer

Quickstart

One key. One observable request.

First create a sandbox app in the Developer Workspace with the smallest required scope. A key is shown exactly once, expires after 180 days and belongs only on your server.

status.sh

curl https://clarity.audecius.com/api/developer/v1/status \
  --header "Authorization: Bearer $CLARITY_API_KEY" \
  --header "X-Request-ID: quickstart-01"

Version 2026-08-12

Nine operations. No hidden effects.

GET /status: Check the project, environment, granted scopes and API version.
Scope · status.read
GET /profile: Read the Developer project identity and its explicit data boundaries.
Scope · profile.read
GET /sessions: Retrieve operator-published Developer dates without access links — never a person's private Clarity Sessions.
Scope · sessions.read
GET /usage: Read 30-day usage only for the authenticated sandbox project.
Scope · usage.read
GET /webhooks: Check your own endpoints and their latest delivery status.
Scope · webhooks.read
GET /tools: Read human-reviewed declarative tool manifests from the library.
Scope · tools.read
POST /tools/validate: Validate a clarity.tool/v1 manifest deterministically.
Scope · tools.validate
POST /tools/preview: Create a non-executing review package with a safety boundary.
Scope · tools.preview
POST /webhooks/test: Create a signed sandbox event and its verification data.
Scope · webhooks.test

validate-tool.sh

curl https://clarity.audecius.com/api/developer/v1/tools/validate \
  --request POST \
  --header "Authorization: Bearer $CLARITY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "manifest": {
      "schema": "clarity.tool/v1",
      "name": "Study outline",
      "entry": "study.outline",
      "consequenceClass": "C1",
      "permissions": ["profile.read"],
      "display": {
        "layout": "list",
        "icon": "list.bullet.rectangle",
        "color": "blue",
        "columns": [
          { "name": "Outline item", "type": "text" },
          { "name": "Done", "type": "toggle" }
        ]
      }
    }
  }'

Authentication

Secrets stay server-side.

Format: Authorization: Bearer clt_test_…
Storage: Clarity stores only the SHA-256 hash. The full secret appears once when issued.
Rotation: Create a new key, update your server, then revoke the old one.
Project boundary: Every key belongs to exactly one app, one environment and a server-confirmed scope list.
Tool permissions: Native tool manifests may currently request only profile.read and sessions.read. Account, health, school and family data remain closed.

Operational contract

Every failure has a stable shape.

400: Invalid JSON or an unknown input.
401: The key is missing, invalid, expired or revoked.
403: The required scope is missing.
413: The request exceeds 64 KB.
422: The manifest violates the clarity.tool/v1 contract.
429: More than 120 requests per minute and key; Reset is returned in the response header.
503: The sandbox cannot safely confirm authorisation and stays closed.

Every response includes X-Request-ID; limits are exposed through X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Requests and errors are aggregated daily by project and operation.