REST APIReviewed 11 October 2026

Claron REST API reference

Use the v1 API for permitted project and issue automation. Match the credential scope to the actual route and check whether an operation completed or only submitted a request.

Base URL and authentication

The hosted base URL is https://api.claron.dev/api/v1. Send Authorization: Bearer with a developer API key and Content-Type: application/json for JSON bodies. Keep credentials outside your code and logs.

Use real project and annotation UUIDs copied from Claron. The examples use illustrative UUIDs that must be replaced. Account roles, visibility, and plan rules still apply after authentication. See API Keys for creation and scope matching.

bash

curl --fail-with-body "https://api.claron.dev/api/v1/projects" \
  -H "Authorization: Bearer $CLARON_API_KEY"

List and read annotations

The list accepts page (default 1), limit (default 20, maximum 100), search, status, severity, type, assignedTo, visibility, buildId, environmentId, release, branch, commit, pageUrl, sortBy, and sortDir, plus supported workflow filters. Use positive integer page/limit values.

List responses contain data (annotation array) and pagination with page, limit, total, and pages. Annotation-detail responses contain annotation, role, plan, and beta. Fields and evidence may be null, restricted, unavailable, or expired; do not treat every report as having all diagnostic fields.

Endpoint	Contract
GET /projects	List projects accessible to the account; project:read.
GET /projects/:projectId	Read the accessible project; project:read.
GET /projects/:projectId/annotations	Read a paginated issue list; project:read.
GET /projects/:projectId/annotations/:annotationId	Read annotation detail and access context; project:read.
GET /annotations/:annotationId/diff	Read the permitted suggested diff; annotation:read.

bash

curl --fail-with-body "https://api.claron.dev/api/v1/projects/00000000-0000-4000-8000-000000000001/annotations?page=1&limit=20&status=open" \
  -H "Authorization: Bearer $CLARON_API_KEY"

Update an issue and inspect approval

PATCH /projects/:projectId/annotations/:annotationId uses project:write. Its body can include title, comment, severity (low, normal, high, critical), status, assignedTo (UUID or null), dueAt (date-time or null), visibility (public or internal), customFieldValues, and wontFixReason.

A permitted direct update returns the updated result. A workflow requiring approval returns HTTP 202 with requiresApproval. That is a submitted request, not confirmation that the requested status has changed; check the approval result and read the issue again.

bash

curl --fail-with-body -X PATCH "https://api.claron.dev/api/v1/projects/00000000-0000-4000-8000-000000000001/annotations/00000000-0000-4000-8000-000000000002" \
  -H "Authorization: Bearer $CLARON_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"severity":"high"}'

Request and decide verification

These POST routes use project:create and their separate role/assignment checks. A scope does not make the caller the assigned verifier. See Verification for the user workflow.

POST under /projects/:projectId/annotations/:annotationId	Body / outcome
/verification/request	verifierId UUID, optional targetBuildId or targetDeploymentId UUID; requests verification on the selected target.
/verification/approve	No request fields; records the permitted verifier's approval.
/verification/reject	reason string of 1–2000 characters; records rejection feedback.

Investigation and asynchronous results

Inspect the returned state and re-read the status at a reasonable interval while work is pending. Stop polling on completion/failure and surface the recorded error. Acceptance does not mean a patch was applied or a pull request merged.

Use Webhooks for event delivery or MCP for bounded read-only evidence. Browser-session WebSocket subscriptions are a separate authenticated interface; they are not a drop-in bearer-key replacement for this REST workflow.

Endpoint	Use
POST /projects/:projectId/annotations/:annotationId/ai/retry	Start/retry a permitted investigation; project:create.
GET /projects/:projectId/annotations/:annotationId/ai/status	Read its investigation status; project:read.
POST /projects/:projectId/annotations/:annotationId/ai/raise-pr	Create a permitted pull request; optional title, body, branchName, and draft; project:create.

Deletion and restoration

Related/duplicate links, merging duplicates, and unmerging are distinct operations and bodies. Do not reuse one generic merge body for all three. Use their dedicated controls unless your automation has the current endpoint's full contract.

Endpoint	Scope / effect
DELETE /projects/:projectId/annotations/:annotationId	project:delete; soft-deletes a report for permitted staff.
GET /projects/:projectId/annotations/trash	project:read; list accessible trash.
POST /projects/:projectId/annotations/:annotationId/restore	project:create; restore during the 30-day window.
DELETE /projects/:projectId/annotations/:annotationId/permanent	project:delete plus owner authority; permanent removal.

Errors and rate limits

Rate limits are endpoint-specific. The outbound webhook-management routes allow 20 requests per minute; MCP allows 120 requests per minute per API key. Do not infer one global REST limit from these values.

Read the route's actual error response rather than assuming every failure has the same body. Avoid retrying a mutation blindly after a timeout: first check whether it already took effect.

Status	Next action
400 / validation error	Check UUIDs, field types, allowed enum values, and required fields.
401	Check the bearer credential, expiry, and revocation.
402	Check the active plan or owning account's applicable credits/limits.
403	Check both scope family/action and effective account permissions.
404	Check the resource and the caller's access; do not assume it exists in this project.
409	Re-read current state and resolve the conflict before retrying.
429	Back off and honor any Retry-After header; do not immediately repeat a loop.