API REFERENCE

REST + WebSocket

How the Claron API works

Every request enters one versioned REST boundary, passes through authentication and permission checks, then reaches a domain router. Fast reads return immediately; builds, AI investigation, screenshots, webhooks, and source-map work are queued and reported back through status records and real-time events.

THE ARCHITECTURE IN ONE VIEW

Edge

REST /api/v1 request ID, headers, rate limit

Domain router

Validate body resolve Actor + access

Command

Return data or enqueue a job

Workers

DB / R2 writes WS + webhook events

The important boundary is accepted versus finished: a successful build or AI-trigger response means the work was accepted by the queue. Poll the resource or subscribe to WebSocket events for completion.

DATA-FLOW DIAGRAMS

LegendExternal entityProcessData store

DFD-0 · SYSTEM CONTEXT

External

Web / CLI / SDK / extension

Users and automation submit commands with their credential type.

Process

P1 · API edge

Auth, scope checks, validation, routing, and request IDs.

Process

P2 · Worker plane

Builds, screenshots, AI work, source maps, and delivery retries.

Store

D1 · PostgreSQL

Actors, projects, annotations, jobs, audit, and delivery state.

External

Git + customer endpoints

Repositories, pull requests, and signed outbound webhook receivers.

Redis/BullMQ and private R2 sit beside PostgreSQL as worker-plane stores. The API acknowledges accepted work; workers later write durable state and publish events.

DFD-1 · REQUEST AND IDENTITY

External

Caller

HTTP method, path, body, and auth credential.

Process

authPlugin

Resolves Actor, expiry, project access, and API-key scope.

Process

Domain route

TypeBox validates input and chooses sync or async behavior.

Store

DB or queue

Transaction result, accepted job, structured error, or later event.

DFD-2 · ANNOTATION AND SOURCE RESOLUTION

External

Live DOM + SDK token

The page contributes DOM context and an opaque cl1. source token.

Process

Extension / overlay

Selects a target and builds annotation, telemetry, screenshot, or replay context.

Process

Annotation API

Persists the finding, resolves identity, and can enqueue AI investigation.

Store

PostgreSQL + private R2

Metadata, status, audit, screenshot, and replay blobs.

Process

Target / source resolver

Checks project access, then uses source maps or SDK deployment locations.

External

Dashboard / CLI

Receives resolved file, line, column, or an explicit unresolved state.

DFD-3 · BUILD, AI, AND WEBHOOK DELIVERY

External

Developer action

Start a build, request investigation, or emit a domain event.

Process

API command

Creates the build/task/delivery record and enqueues durable work.

Store

Redis / BullMQ

Queue state, leases, retries, and backoff.

Process

Worker + broadcaster

Runs the job, writes DB/R2, signs webhooks, and emits realtime events.

The web UI consumes both the mutation response and the event stream. It must reconcile by resource ID and tolerate reconnects, retries, and duplicate delivery.

BASE URL AND REQUEST CONTRACT

request.sh

bash

API_BASE="https://api.claron.dev/api/v1"
curl "$API_BASE/projects" \
  -H "Authorization: Bearer bd_<your-api-key>" \
  -H "Content-Type: application/json"

Production prefix: https://api.claron.dev/api/v1 (use NEXT_PUBLIC_API_URL in the web client)
Development tools: Swagger is available at /swagger outside production; static overlay assets are served under /static.
Successful response: The route returns its JSON resource or an accepted/queued result. Long-running work continues in a worker.
Validation failure: HTTP 400 with code BAD_REQUEST and a details object/array from the schema validator.

AUTHENTICATION AND SCOPE RESOLUTION

Credential types

auth_session cookie or Bearer session token: browser/user access.

bd_...: developer API key for REST automation and CLI.

sdk_...: SDK credential used for deployment/source-map uploads.

ext_...: extension device token; project access still requires an approved grant.

x-session-token: guest review session, limited to its invited project.

Scope grammar

text

<resource>:<action>
project:read
annotation:write
webhooks:*

API-key authorization normalizes the first URL resource segment to singular form. In practice, GET maps to read, POST to create, PATCH/PUT to write, and DELETE to delete. An exact scope, a resource wildcard, or * can satisfy a check.

Keep credentials server-side

bd_ and sdk_ secrets are shown once and should live in a secret manager or CI variable. Source-location tokens are opaque and are not a substitute for an API credential.

REST ROUTE FAMILIES

Identity

/auth/*

Sessions, OTP verification, OAuth, password recovery, and the short-lived WebSocket token.

Workspace

/my/work, /search

Paginated action-inbox rows and access-checked search across projects, annotations, and permitted comments.

Projects

/projects/*

Project lifecycle, membership, settings, builds, environment variables, and exports.

Annotations

/annotations/*, /projects/:projectId/annotations/trash

Create and triage findings, manage saved views, search duplicate candidates, reversibly merge reports, and restore trashed annotations.

Builds

/projects/:projectId/build*

Queue, wake, inspect, cancel, prioritize, and read logs for a project build.

Automation

/webhooks/outbound, /sdk/*

Deliver events asynchronously and upload SDK deployment manifests/source maps.

Collaboration

/review-sessions/*, /guest/*

Run authenticated or guest review sessions and persist replay events.

Notifications

/notifications/*

Read and snooze your inbox; manage event channels, digest cadence, timezone, quiet hours, and per-project delivery modes.

DUPLICATE CANDIDATES AND MERGES

Duplicate suggestions are deterministic and non-blocking. Authenticated project members can query candidates; invited guests can query only public annotations in their project. Owners, developers, and testers can merge or undo a merge. A merge keeps the reported annotation and its comments/evidence intact, transfers missing tags and subscribers to the canonical issue, and writes history plus an audit event.

http

POST /projects/:projectId/annotations/duplicate-candidates
POST /projects/:projectId/annotations/:annotationId/merge
POST /projects/:projectId/annotations/:annotationId/unmerge
{ "canonicalAnnotationId": "<issue-uuid>" }

Normal annotation lists hide duplicates by default. Pass duplicates=show to include them or duplicates=only to inspect them. Similarity never triggers an automatic merge.

ANNOTATION TRASH AND RETENTION

Deleting an annotation is a reversible soft delete. Project staff can list and restore trashed issues; only the project owner can permanently delete one. Items remaining in Trash are purged after 30 days. The database deletion and object-purge job are committed together, then private evidence cleanup runs and retries failures.

http

DELETE /projects/:projectId/annotations/:annotationId
GET /projects/:projectId/annotations/trash?limit=30&cursor=<cursor>
POST /projects/:projectId/annotations/:annotationId/restore
DELETE /projects/:projectId/annotations/:annotationId/permanent

SYNCHRONOUS AND ASYNCHRONOUS FUNCTIONS

Synchronous: Auth, project reads, annotation CRUD, comments, filters, membership, settings, API-key management, and delivery-log reads.
Queued: Builds, AI investigation/verification, screenshot processing, SDK deployment ingestion, inbound sync, and outbound webhook delivery.
Worker result: Workers update the database or R2, then publish build/annotation/notification events. The API never makes a caller wait for the entire pipeline.
Client behavior: Keep the returned ID, poll the resource when needed, and use the WebSocket for responsive UI updates. Treat duplicate event delivery as possible.

Web client function map

request: Adds the API base path, credentials, JSON headers, and parses structured errors.
requestBlob: Runs the same request contract for binary downloads such as replay exports.
requestWithUploadProgress: Uses XMLHttpRequest so uploads can report progress while preserving ApiError handling.
connectRealtimeSocket: Fetches a temporary WebSocket token, connects, heartbeats every 30 seconds, and reconnects with backoff.

WEBHOOK AND WEBSOCKET EVENTS

POST webhook body

json

{
  "event": "annotation:created",
  "data": { "annotationId": "ann_01HZ..." },
  "ts": 1760000000000
}

Outbound webhooks are queued in BullMQ. Delivery uses POST, a 10-second timeout, optional X-Claron-Signature: sha256=<hex>, and up to five attempts with exponential backoff. Non-2xx responses are failures and appear in delivery logs.

WebSocket event

json

{
  "event": "build:success",
  "data": { "id": "...", "status": "success" },
  "ts": 1760000000000
}

The browser first calls GET /auth/ws-token, then connects to /realtime. The client sends a ping every 30 seconds and reconnects with capped exponential backoff.

ERRORS, SECURITY, AND SOURCE OF TRUTH

structured error

json

{
  "error": "Validation Error",
  "code": "BAD_REQUEST",
  "message": "Invalid request body",
  "details": { "field": "url" }
}

All routes share schema validation, actor resolution, access checks, rate limiting where configured, structured errors, and request logging. Secrets use AES-256-GCM at rest; private R2 objects are accessed through managed keys or short-lived URLs.

Configure API keys

CONTINUE

API Keys

Create scoped bd_ credentials.

Webhooks

Configure signed async delivery.

SDK

Upload private deployment mappings.