One API. Your tools.
The API uses versioned paths such as /api/v1. Send JSON over HTTPS. The examples use this server's base URL:
https://commitscale.com/api/v1
Responses use JSON too. Optional fields may be absent. A field described as nullable may be null when it has no value. Use the response schema to tell the two apart.
New fields can appear without a new version. Ignore fields you do not know.
The API reference is generated from the deployed server's description. It includes the operations available through Free or Pro features. An operation may also require ownership, a particular credential, or a confirmation.
Get credentials for curl
The CLI handles sign-up, credentials and retries for you. For a direct integration, start sign-up. The person confirms the email link before your tool can collect its check key. An existing user signs in and creates a check-only key for an integration:
cscale auth login --email you@example.com
cscale key create --name curl --print
The person approves sign-in and, if their passkey layer is on, confirms key creation. The second command shows the new key once. Put it in a secret store, then supply it to curl from there.
Send the key in the Authorization header:
Authorization: Bearer $CSCALE_CHECK_KEY
For example, after loading the key into that environment variable from your secret store:
curl --fail-with-body -H "Authorization: Bearer $CSCALE_CHECK_KEY" 'https://commitscale.com/api/v1/check-keys/current/usage'
Choose a credential
| API action | Check-only key | Personal sign-in |
|---|---|---|
| Start a model check and ask its questions | Yes | Yes |
| Read daily check-key request counts | Its own only | No; use the check key itself |
| Read the acceptance policy and namespace usage | Yes; usage only for its owner's personal namespace | Yes, subject to access |
| Contact support or withdraw data sharing | Yes | Yes |
| Read the data-sharing choice or opt in | No | Yes; opt-in is for Free |
| Read a namespace plan; manage an account, keys or billing | No | Yes, subject to access and confirmation |
A regular agent credential is distinct from a check-only key. Some account actions need a freshly signed-in browser or passkey confirmation even with a personal sign-in. The API reference describes each operation's requirements.
For account management and namespace plans, use a personal access token or a signed-in browser session. The CLI's sign-in stays private and the CLI does not print it. To obtain a separate personal credential for curl, use the device flow:
- Start a device login by posting JSON with your email to
/api/v1/auth/device. Keep the returned device code private and show the user code to the person. - The person opens the emailed link, types the user code shown by the terminal, and approves. The link lasts 15 minutes. Five wrong codes refuse the login; start again if that happens.
- Poll for the credential by posting the device code to
/api/v1/auth/device/token, no faster than the returned interval. The approved response contains a personal token once; put it in a secret store for curl. Stop onaccess_denied. Start again if the login expires or was refused after five wrong codes.
For example, start the flow with curl and capture the JSON in a private place:
curl -X POST 'https://commitscale.com/api/v1/auth/device' -H 'Content-Type: application/json' -d '{"email":"you@example.com"}'
Send the returned device code as the device_code field when polling. Do not put the response or credential in logs. Some actions require a browser that the person signed in to, even with a personal token; follow the operation's description. Requests that change data with a session cookie must send this server's origin. Browser sign-in and email verification steps may also require that origin.
New keys are shown once. Store them in your credential store. Keep credentials out of URLs, logs and source control.
Ask a question
Start a check with a fresh Idempotency-Key and a random UUID as its check_id, generated by your client. Send that same check_id when you ask a test question about the relevant code excerpt. The answer includes a yes/no choice and its probability. Use it as evidence for the test check, alongside local test results.
Give each question a fresh Idempotency-Key. If a response is lost, retry with the same key and identical body. A completed question replays its saved answer within the replay window. Reusing a key with another body returns idempotency_key_reused. An expired replay returns model_replay_expired; that identity cannot run again.
If a question is already queued or running, idempotency_key_in_use says when to retry in Retry-After. A busy organization can also refuse a start with unavailable and Retry-After; retry the same body and key after that delay.
Usage and the Free allowance
Free includes 100 checks per person per UTC calendar month across Free workspaces. Starting a check counts it against its workspace; exact retries and its questions do not count again.
Verified addresses that reach the same inbox share the Free allowance. Pro has no monthly check cap, with fair use. The API calls Pro pro and accepts team as an input alias. Namespace usage includes the count, the cap and the next reset time. Check-key usage counts API requests, including failures; it is a different measure.
If the allowance is used, model_check_cap_reached refuses a new check. A check already started can finish within its replay window and question bound.
Problems tell you what to do next
Errors use application/problem+json. Read the stable code in your program. The title and detail explain the problem to a person; their wording may change.
{
"type": "https://commitscale.com/errors/unauthenticated",
"title": "Sign in required",
"status": 401,
"code": "unauthenticated"
}
Each operation lists its problem codes. Follow next.action when present. For a retry, respect Retry-After and next.after_s. A feature refusal points you to your plan. Read the problem reference for meanings and next steps.