Public API resources

SubraLabs publishes one small public API for anonymous Sense-Calibrator telemetry. Its complete, machine-readable contract is available as OpenAPI 3.1 JSON. No API key or user account is required.

When to use this API

The submission endpoint exists only for the Sense-Calibrator web tool. Call it after a controller calibration when the person using the tool has given explicit opt-in for that individual technical result. It is not a general contact API, analytics collector, model endpoint, or substitute for emailing SubraLabs. A rejected or unavailable telemetry request must never stop the calibration workflow.

The health endpoint may be used to determine whether the telemetry service is available. It does not promise that a later submission will be accepted and must not be polled aggressively.

Endpoints

GET /api/calib/health returns a minimal JSON health object. POST /api/calib/v1/sessions accepts the typed calibration record defined in the OpenAPI document and returns 204 No Content on success. Unknown fields and invalid values are rejected. The service stores no account, name, email address, request User-Agent, or IP address in the telemetry record.

Authentication and privacy

These endpoints do not use authentication. Browser submissions are limited to the documented Sense-Calibrator origins through CORS; CORS is not treated as authentication. The absence of credentials does not remove the need for explicit opt-in. The privacy policy describes the fields and the no-request-metadata boundary.

Rate limits

Calibration submissions are limited to 10 requests per IP address in a rolling 60-second window. Responses expose the current IETF draft conventions through RateLimit-Policy and RateLimit, plus compatibility fields RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. A 429 response also includes Retry-After. Clients should use the headers they understand and never send more traffic because a displayed quota appears available.

Machine-readable errors

API errors use application/problem+json following RFC 9457. Every body contains type, title, status, detail, a stable code, and a resolution hint. The legacy error field mirrors detail so the existing calibrator remains compatible.

• invalid_request. Correct the JSON body against the OpenAPI schema before retrying.
• payload_too_large. Remove undocumented data and keep the body below 8 KB.
• unsupported_media_type. Send uncompressed application/json encoded as UTF-8.
• rate_limit_exceeded. Wait for the number of seconds in Retry-After.
• storage_capacity_reached. Continue without telemetry and do not retry automatically.
• endpoint_not_found. Use a path and method listed in the OpenAPI document.
• internal_error. Continue without telemetry and do not retry immediately.

Agent and function-calling compatibility

Each operation in openapi.json has a unique operationId, a description, typed request and response schemas, and explicit failure responses. An agent may translate those operations into function tools, but it must preserve the usage and consent rules above. For a software project enquiry, use the human contact route instead.