Hosted API

The hosted service runs the statistics engine of cci-sdk 0.1.1, unmodified, behind an authenticated HTTP API. Around it, it adds what a shared service needs: your own provider credentials stored as encrypted connections, a calibration lifecycle with background jobs, monitors and audits, idempotent retries, rate limits, and a trace of every request. This page is the operational contract; request and response shapes are on API reference.

Base URL and authentication

https://cci.gitdate.ink/api/v1

This is the SDK’s default base_url. Every route except GET /v1/healthz and GET /v1/readyz needs an API key:

Authorization: Bearer cci_live_...

export CLI_API_KEY=cci_live_...
export CLI_BASE_URL=https://cci.gitdate.ink/api/v1     # optional: this is the default

from cli_sdk import CLIClient
 
client = CLIClient()       # reads CLI_API_KEY and CLI_BASE_URL

For a self-hosted deployment, point CLI_BASE_URL at it. The SDK accepts a missing key only when the URL’s host is localhost, 127.0.0.1, 0.0.0.0 or ::1.

API keys and scopes

Create keys under Dashboard > API keys. The full key is shown once; the service stores only a SHA-256 hash and a short display prefix. A key acts in the organization it was created in, and carries one or more scopes:

• New keys default to evaluate profiles:write. Keys created before scopes existed behave as evaluate profiles:write.
• A key never has more than its creator: its effective scopes are its stored scopes intersected with what the creator’s current role allows. A viewer can only create telemetry:read keys. Role changes apply on the key’s next request.
• A key whose creator leaves the organization stops working (401 key_owner_removed).
• A missing scope is 403 insufficient_scope, with WWW-Authenticate: Bearer error="insufficient_scope", scope="..." naming the scope to add.

Use separate keys per service, so a leaked or revoked key affects one workload, and so Usage shows cost per service.

Bring your own provider key

The hosted service holds no shared provider credential. Every model call uses a provider connection that your organization stored: an encrypted OpenAI, Anthropic, Gemini, Bedrock or other key, or the URL of your own vLLM or SGLang server. Without one, evaluate returns 422 connection_required with field: "backend.connection".

A backend uses the organization’s default connection for its provider, or the one it names:

from cli_sdk import OpenAIBackend
 
OpenAIBackend(model="gpt-4.1-2025-04-14", connection="openai-prod")
# equivalent dict: {"provider": "openai", "model": "gpt-4.1-2025-04-14", "connection": "openai-prod"}

With a CustomBackend the SDK computes evidence in your process and the server never calls a model, so no connection is needed.

Providers and access levels

The levels above auto come from the connection’s capability probe: the service records what a self-hosted server or an imported Bedrock model supports when you run Test on the connection. Details and examples per provider are on Backends and Provider connections.

• A Set with more than 20 options cannot be scored from first-token log-probabilities, so it runs at L0 on providers whose auto level is L1.
• An access_hint (or a Set’s backend_access_hint) pins a level: sampling (L0), logprobs (L1), prompt-scoring (L2), exact (L3), hidden-state (L4). A level the backend cannot reach fails with 502 access_level_unavailable before any model call is made. hidden-state serves Set, Belief, Gate and Interval queries.
• At L0 each score is built from sample_count samples: 8 by default, at most 32, set per backend (AnthropicBackend(sample_count=...), or "sample_count" in a backend dict). The sample count is part of the profile’s fingerprint.

Request ids and correlation

Every response carries x-request-id: req_<16 hex digits>, and every JSON body includes the same value as "request_id". The SDK exposes it as result.request_id. Log it next to any decision you act on: it opens the request’s trace in the dashboard and in GET /v1/requests/{id}.

To tie a request to your own logs you can send:

• x-request-id in the same req_<16 hex> format. It is adopted unless the service has seen it in the last day, in which case a new id is minted. Do not put it in default_headers, where every request would share it.
• A W3C traceparent header. Its trace id becomes the request’s trace id.
• The X-CCI-* correlation headers (session, thread, run name, environment, agent, tool call, tags, metadata), listed on Observability.

Invalid correlation headers never fail a request: they are dropped, and the request’s trace records a warning naming the header (an evaluate response also lists it in warnings).

Idempotency

Every POST, PUT, PATCH and DELETE may carry an Idempotency-Key header (1 to 255 printable ASCII characters). The SDK sends a fresh UUID for each logical POST and reuses it across that call’s retries, so a retried write is applied once.

Keys are scoped to your organization and the API key that sent them. Responses with status 2xx, 400, 404, 413, 415, 422 and 424 are stored for replay. Responses a retry could change (401, 402, 403, 408, 409, 429, 5xx, 529) are not stored, so a retry runs again.

Rate limits and concurrency

Every 429 and 529 carries Retry-After in seconds. Rate-limited routes also return RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Limits your provider enforces on your own key come back as 429 provider_rate_limited (with the provider’s Retry-After), 529 provider_overloaded, or 402 provider_quota_exhausted.

The SDK retries 429, 502 and 529 with full-jitter exponential backoff, honoring a numeric Retry-After of up to 60 seconds. It does not retry 402: an exhausted quota needs attention on the provider account. See Errors and retries.

Timeouts and background jobs

Raise the SDK’s timeout for synchronous audits and first calibrations, for example CLIClient(timeout=300). A 504 is not retried by the SDK; it raises CLIError("HTTP 504: ...").

Work that would take long runs as a persisted background job:

• Calibration. When the first evaluate against a profile needs more than 200 estimated model calls to score its examples, calibration runs as a job. Until it finishes, evaluate answers with 424 and heuristic-labelled answers, plus a warning naming the job (the SDK returns them; with strict_guarantees=True it raises). Smaller calibrations run inline, within the request.
• Appended examples. Examples added to a calibrated profile are scored inline when cheap, otherwise by a job; the profile card then shows pending_n and job.
• Explicit work. POST .../calibrate, an audit sent with "async": true, and a large label-with-judge pool return 202 Accepted with the job.

Poll a job until it leaves queued and running:

import os
import time
 
import httpx
 
API = os.environ.get("CLI_BASE_URL", "https://cci.gitdate.ink/api/v1").rstrip("/")
HEADERS = {"Authorization": f"Bearer {os.environ['CLI_API_KEY']}"}
 
 
def wait_for_job(job_id: str, every: float = 5.0) -> dict:
    while True:
        job = httpx.get(f"{API}/jobs/{job_id}", headers=HEADERS, timeout=30).json()
        if job["status"] not in ("queued", "running"):
            return job        # "succeeded", "failed" or "cancelled"
        time.sleep(every)

A job has id, kind, status, profile, progress ({done, total}), estimated_calls, actual_calls, result, error, created_at, started_at, finished_at and request_id (the request that queued it). GET /v1/jobs?profile=&status=&limit= lists jobs, and POST /v1/jobs/{id}/cancel cancels a queued or running one. Jobs survive a restart of the service: running jobs go back to the queue.

Limits

Status codes

Every error body is {"message", "code", "field"?, "details"?, "request_id"}. The full code catalog is on Errors and retries.