Submit predictions for scoring

POST /v1/evals

Queues an eval job. Inline predictions are capped at 5 MB of JSON. Poll GET /v1/jobs/{id} for the result.

Credential. An API key (jean_live_…) or a dashboard session token.

curl --fail-with-body -X POST "https://api-833252724876.us-central1.run.app/v1/evals" \
  -H "Authorization: Bearer $JEAN_API_KEY" \
  -H "Idempotency-Key: YOUR-UNIQUE-REQUEST-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "nightly",
    "predictions": [
      {
        "item_id": "item_4211",
        "prediction": [
          "item_88",
          "item_12",
          "item_5"
        ]
      },
      {
        "item_id": "item_4212",
        "prediction": [
          "item_31",
          "item_7",
          "item_99"
        ]
      }
    ],
    "suite_id": "suite:smoke-v1"
  }'

Body

Field	Type	Required	Notes
suite_id	string	yes
predictions	object[] or null	no	Inline predictions. Capped at 5 MB of JSON.
input_ref	string or null	no	An upload ref from POST /v1/uploads (kind predictions) instead of inline.
label	string or null	no

Response · 202

{
  "id": "job_q1w2e3r4t5y6u7i8o9p0",
  "org_id": "org_k3j2h4g5f6d7s8a9q0w1",
  "type": "eval",
  "status": "queued",
  "request_id": "req_z9x8c7v6b5n4m3l2",
  "label": "nightly",
  "versions": {
    "hfm_sha": "9f2c1ab4d7e0",
    "suite_id": "suite:smoke-v1"
  },
  "attempts": 0,
  "created_at": "2026-01-15T09:30:00Z",
  "started_at": null,
  "finished_at": null
}

Errors

Status	Meaning
401	Unauthenticated, invalid token or revoked key.
403	Forbidden, session required or org required.
413	Inline predictions exceed the 5 MB cap.
422	Validation failed.
429	Quota or rate limit exceeded; error.details says which, and when.
500	Internal error; quote error.request_id when reporting it.

Every one carries the same envelope.

API overview · Full contract