Partner API, version 1

Authenticate every /v1 request from your server with a project API key: Authorization: Bearer lsk_live_…. A key belongs to exactly one project; nothing in a request can choose another. Never ship a key to a browser or app.

Download the API description: one machine-readable file listing every route, field and error, in the standard format that API tools such as Swagger UI and Postman import. It describes HTTP endpoints only; this service calls no model provider.

Both clients are published as outfigure under the MIT licence. They use the API’s own field names, retry network failures and 429, 502, 503 and 504 with the same idempotency key, and send nothing but your requests.

The npm package also brings the tools that audit an export of your logs on your own computer, npx outfigure outcome-audit and npx outfigure readiness. They read and write local files and open no network connection.

npm install outfigure
pip install outfigure

outfigure on npm · outfigure on PyPI

Record each intervention when it is delivered, with contract.template to open an Outcome Contract, and each later check as evidence. Both are append-only: the same record sent again is stored once, and different content under the same ID returns 409. Batches of up to 100 are atomic, and every write needs an Idempotency-Key. Receipts are issued by the job drain, never inside the request.

{
  "schema_version": "1.0",
  "intervention_id": "dt_int_88",
  "learner_id": "dt_learner_0089",
  "capability": "geometry.area_rectangles",
  "class": "contrast_case",
  "delivered_at": "2026-09-02T08:32:00.000Z",
  "source": "demotutor",
  "session_id": "dt_session_88",
  "agent_id": "demotutor_math",
  "model_provider": "synthetic",
  "model_name": "demotutor-model",
  "prompt_policy_version": "demotutor-2026.09.1",
  "turn_count": 6,
  "contract": {
    "template": "durable_capability_gain"
  }
}

Register an https endpoint for outcome.receipt.created, outcome.receipt.updated, outcome.contract.expired, experiment.data_ready, experiment.sample_ratio_mismatch, experiment.guardrail_triggered, experiment.release_advice_changed and data_quality.degraded. Each notice carries identifiers and statuses only; read the receipt with your key for the rest.

• OutFigure-Signature is t=<unix seconds>,v1=<hex>: HMAC-SHA256 of <t>.<raw body> under your endpoint's secret, one v1 per valid secret while a rotation is under way. Refuse a timestamp more than 5 minutes from your clock.
• OutFigure-Webhook-Id stays the same on every retry and replay: record the ones you have handled. Delivery is at least once.
• Anything but a 2xx answer within ten seconds is retried, up to 8 attempts over about two days. Redirects are never followed.

One observed learning event. Required for all types: schema_version, event_id, event_type, learner_id, occurred_at, source. Responses additionally require item_id, item_version, attempt_id, attempt_number, response_kind and the outcome that matches the kind. Unknown fields, and fields that try to name a project or tenant, are rejected rather than ignored.

{
  "schema_version": "1.0",
  "event_id": "evt_0001",
  "event_type": "response",
  "learner_id": "learner_demo_01",
  "occurred_at": "2026-09-14T12:40:31Z",
  "source": "partner_backend",
  "session_id": "session_01",
  "item_id": "question_012",
  "item_version": "1",
  "attempt_id": "attempt_01",
  "attempt_number": 1,
  "response_kind": "binary",
  "correct": true,
  "assistance": "none",
  "hint_count": 0,
  "feedback_seen": false
}

{
  "learner_id": "learner_demo_01",
  "concept_id": "networking.dns",
  "status": "insufficient_evidence",
  "summary": {
    "window": "latest_200_eligible_events",
    "eligible_attempts": 1,
    "correct_attempts": 1,
    "observed_accuracy": 1,
    "distinct_sessions": 1
  },
  "forecast": null,
  "uncertainty": { "kind": "not_estimated", "interval": null, "calibration_status": "unvalidated" },
  "flags": ["sparse_history", "insufficient_sessions"],
  "model_version": "observed-v0",
  "eligibility_version": "eligibility-v2"
}

Why a response does not count (eligibility-v2)

partial_credit

Scored on a rubric, not right or wrong.

unscored

No outcome was recorded.

answer_revealed

The answer was shown before the attempt.

collaborated

Worked on with someone else.

assistance_unknown

No record of whether help was used.

assisted

Hints or outside help were used.

feedback_seen

Feedback was visible while answering.

hint_before_response

A hint was shown before the answer.

feedback_before_response

Feedback was shown before the answer.

repeat_in_session

The item was already answered in this session.

repeat_in_attempt

The item was already answered in this attempt.

A check plan lists where one independent response (explicitly unassisted, scored, first in its session) would most improve the evidence about a learner, with the reason and the evidence behind each check. The rule is next-check-v0, and its version is carried on every plan. A plan is returned to your product, which decides what to do with it; OutFigure never contacts a learner.

Errors share one shape: {"error": {"code", "message", "request_id", "details"}}. Messages never repeat submitted values. Retry network failures and 429, 502, 503 and 504 with the same idempotency key; do not retry other 4xx errors unchanged.