DOCS · SDK quickstart

From registerto your first signed record.

The same registration endpoint the dashboard uses — wrapped here as a single public walkthrough so a new operator can see the wiring before signing in. Five minutes from a registration curl to a SHA-256 record chained into your ledger.

Step 01 · Register

Register a model.

The registration endpoint mints a one-time pl_… API key (only its SHA-256 is stored) and returns paste-runnable Node + Python snippets that the dashboard already wires for you after the call. It's gated by your signed-in session — paste your __Secure-better-auth.session_token cookie in place of $YOUR_SESSION_COOKIE below.

curl · POST /api/models/register
paste-run
curl -X POST \
  https://plumbline-ai-9.polsia.app/api/models/register \
  -H "Content-Type: application/json" \
  -b "__Secure-better-auth.session_token=$YOUR_SESSION_COOKIE" \
  -d '{"name":"eval-claude","version":"0.1.0","owner_team":"ai-eval-team"}'

Response envelope (mirrors ModelRegisterResult):

JSON · response shape
paste-run
{
  "model_id":  "<your_model_id>",
  "api_key":   "pl_<64-hex>",         // shown ONCE — only sha256 is stored
  "snippets": {
    "node":   "POLSIA_API_KEY=… POLSIA_MODEL_ID=… POLSIA_MODEL_VERSION=0.1.0 POLSIA_API_BASE=… node -e \"import('@plumbline/eval-sdk').then(m=>m.recordEval({input:'hello',output:'hi',version:'0.1.0'}))\"",
    "python": "POLSIA_API_KEY=… \\\n POLSIA_MODEL_ID=… \\\n POLSIA_MODEL_VERSION=0.1.0 \\\n POLSIA_API_BASE=… \\\n python -c \"from polsia import record_eval; record_eval(input='hello', output='hi', version='0.1.0')\""
  }
}

Step 02 · Install

Install the SDK.

Two paths to the same wire. The Node one ships in this repo today (sdks/eval-sdk/); the Python one is illustrative — the package isn't published yet, but the env-var stack already matches the dashboard's install shape.

Node · @plumbline/eval-sdk
paste-run
POLSIA_API_KEY=pl_<polsia-api-key> \ POLSIA_MODEL_ID=<polsia-model-id> \ POLSIA_MODEL_VERSION=<polsia-model-version> \ POLSIA_API_BASE=https://plumbline-ai-9.polsia.app \ node -e "import('@plumbline/eval-sdk').then(m=>m.recordEval({input:'hello',output:'hi',version:'<polsia-model-version>'}))"
Python · polsia (illustrative)
paste-run
# Illustrative Python snippet — the 'polsia' package is not published yet.
POLSIA_API_KEY=pl_<polsia-api-key> \
POLSIA_MODEL_ID=<polsia-model-id> \
POLSIA_MODEL_VERSION=<polsia-model-version> \
POLSIA_API_BASE=https://plumbline-ai-9.polsia.app \
python -c "from polsia import record_eval; record_eval(input='hello', output='hi', version='<polsia-model-version>')"

Step 03 · Capture

Trigger your first evaluation.

The SDK does this wire for you on the Node path — paste-run the Node snippet above and skip the curl. Need to see the raw shape? Hit /api/eval-records directly with the bearer key the registration call minted. Body matches EvalRecordCreate; the response is the right-rail sample on this page.

curl · POST /api/eval-records
paste-run
curl -X POST \
  https://plumbline-ai-9.polsia.app/api/eval-records \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pl_<polsia-api-key>" \
  -d '{
    "model_id":  "<polsia-model-id>",
    "run_id":    "smoke-test-001",
    "version":   "0.1.0",
    "input":     {"prompt":"hello"},
    "output":    {"text":"hi"}
  }'

Next · Pick a direction

Pasted it. Now where?

See a real chain-record against the public demo model, or look at what running this in production actually costs.

See a live signed recordWhat it costsVerify a receipt