Freshness is explicit
Successful responses include meta.organizationId and meta.freshness. The freshness source is database, collector, provider or local_preview; status is current, stale, unavailable or synthetic. updatedAt can be null and note explains important gaps. Treat stale, unavailable and synthetic data as real states, not empty success. X mentions and token reads use persisted data; active clients mark those sources as watched for the background collector, but no API request forces a paid provider refresh.
{
"data": [],
"meta": {
"organizationId": "org_example",
"freshness": {
"source": "collector",
"updatedAt": null,
"status": "unavailable",
"note": "No X mention collection has completed."
}
}
}
ETags avoid unchanged payloads
Save the ETag header and send it back in If-None-Match. An unchanged authorized response returns 304 with no body. Authentication, live eligibility and quota checks still happen before that response. Authenticated data is private and varies by Authorization; do not put it in a shared cache.
# First request: save the ETag response header.
curl -i -H "Authorization: Bearer ${CLAIRE_API_KEY}" \
"${CLAIRE_API_URL}/context"
# Later: unchanged data returns 304 with no response body.
curl -i -H "Authorization: Bearer ${CLAIRE_API_KEY}" \
-H 'If-None-Match: "etag-from-the-first-response"' \
"${CLAIRE_API_URL}/context"
Rate and error semantics
Shared limits are 120 requests per minute per key, 600 per organization, and 300 per IP address on early access; the top plan, which comes with a verified 25,000 $CLAIRE holding or the Pro plan, raises the first two to 360 and 1,800. Read RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset on responses; RateLimit-Limit is the limit that applies, and reset is the number of seconds until the current window ends. A 429 also supplies Retry-After; wait that long instead of retrying immediately.
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 42
Retry-After: 42
Application errors use {"error":{"code":"…","message":"…"},"requestId":"…"}. Expect 400 for invalid input, 401 for a missing or unusable credential, 403 for a missing scope, 404 for an inaccessible resource, 405 for the wrong method, 413 for a request body, 429 for a limit, 503 when a required dependency is unavailable, and 504 for a processing timeout. Quote the matching X-Request-Id header when asking for help.
GET /api/v1/assets?page=0
HTTP/1.1 400 Bad Request
X-Request-Id: 7d0d4ec5-846c-4f3e-a62d-1433cfb4f851
{
"error": {
"code": "invalid_parameter",
"message": "page must be between 1 and 10000."
},
"requestId": "7d0d4ec5-846c-4f3e-a62d-1433cfb4f851"
}