API and SDK reference.
Everything in the portal is an API call. Authenticate with a scoped key or an SSO session and drive the whole flow from code.
Authentication
Create a workspace at app.needset.ai/signup (free, no card). People sign in with a one-time email link or SSO; workloads use API keys. Send the key in the Authorization header. Keys are tenant-scoped and role-scoped; admins issue them in the portal under Access.
curl -H "Authorization: Bearer $NEEDSET_API_KEY" https://app.needset.ai/v1/data/assetsRoles
| Role | Can |
|---|---|
| viewer | Read assets, plans, explanations, pilots, proofs, audit |
| operator | Everything a viewer can, plus register, upload, import evals, record failures, compile plans |
| approver | Approve pilots. In production this requires an SSO principal |
| auditor | Read and verify the audit chain, create and verify anchors |
| admin | Manage keys, schedules, webhooks and tenant settings |
Core resources
| Resource | What it is |
|---|---|
/v1/data/assets, :upload, :ingest, :register, :scan | Cataloged assets with chunk stats, lineage and codec; upload, in-place ingest, S3 registration and prefix scan |
/v1/data/assets/{id}:optimize, :verify, :approve, :activate, :rollback, :materialize, :download | Representation lifecycle: optimize, verify, approve, activate, roll back, stream out |
/v1/failures, /v1/failures:batch, /v1/candidates | Recorded model failures (single or batch, including lm-eval imports) and candidate assets that define demand and supply |
/v1/plans:compile, /v1/plans/{id}, /v1/plans/{id}:explain | Compile a deterministic plan; read it with its verification; read the full explanation |
/v1/pilots, /v1/pilots/{id}:evaluate, :activate, :rollback, /observations | Governed pilots bound to a plan, with observations, eligibility evaluation, approval and rollback |
/v1/economics:estimate, /v1/savings:prove, /v1/savings:export.csv | Unit-cost estimates, signed savings proofs and CSV export |
/v1/audit, /v1/audit:anchor, /v1/audit:attest | The HMAC audit chain, signed anchors and attestation verification |
/v1/schedules, /v1/webhooks, /v1/webhooks:test | Automation: scheduled recompiles and HMAC-signed event delivery |
/v1/metrics, /v1/metrics/prometheus | Tenant metrics as JSON and as a Prometheus scrape target |
/v1/api-keys, /v1/whoami, /v1/auth/config | Key issuance and revocation, principal lookup, SSO configuration |
/v1/account, /v1/account/users, /v1/storage/connection, /v1/billing/* | Workspace plan and usage, team invites, customer bucket connection, Stripe checkout and billing portal |
Python SDK
The client depends only on the standard library. It streams uploads and never buffers a file in memory.
from needset.client import Needset
ns = Needset("https://app.needset.ai", api_key=KEY)
ns.data.upload("shards-2026-09-29", "shards/2026-09-29.tar")
ns.failures.record(need="code", weight=1.0, model_version="v12",
evidence="unit tests failing on async")
plan = ns.plans.compile(byte_budget=2_000_000_000, decode_ms_budget=8_000)
assert ns.plans.get(plan["plan_id"])["verification"]["valid"]Webhooks
Each delivery carries an X-Needset-Signature header, an HMAC-SHA256 of the body with the endpoint secret. Verify it before acting. Events cover plans, pilots, proofs, anchors and schedule runs.
Self-hosting
The platform ships with a Compose file (PostgreSQL, the service, a Caddy gateway) and a Kubernetes manifest. Secrets are read from files. A single command brings a hosted instance up with a public certificate.
The full endpoint reference and the SDK source are delivered with every platform and self-hosted engagement. Contact us for access.