REST API

Tanvrit Compute exposes a small REST surface over https://api.tanvrit.com. It is the canonical transport for the SDK, the CLI, the web portal, and any first-party integration. You can call it directly from any HTTP client.

Authentication

Every request must carry one of:

| Header | Used by | |---|---| | Authorization: Bearer <JWT> | Portal + CLI interactive sessions | | X-API-Key: tnv_<key> | Agents, CI runners, SDK-in-prod |

JWTs are issued by POST /api/auth/verify-otp. API keys are minted from the portal's Settings → API Keys screen (or via /api/compute/api-keys/create with a live JWT). See security for the full credential model.

Core compute endpoints

All paths accept and return application/json.

Jobs

POST /api/compute/jobs/submit       — enqueue a new job
POST /api/compute/jobs/retrieve     — fetch one job by id
POST /api/compute/jobs/list         — paginated list with filters
POST /api/compute/jobs/cancel       — cancel a queued or running job
POST /api/compute/jobs/retry        — requeue a failed or timed-out job
GET  /api/compute/jobs/{jobId}/logs — SSE stream of stdout/stderr lines

Nodes (agent plane)

POST /api/compute/nodes/register    — agent first contact
POST /api/compute/nodes/heartbeat   — keep-alive (every 30 s)
POST /api/compute/nodes/poll        — ask for assigned jobs
POST /api/compute/nodes/result      — submit a terminal job result
POST /api/compute/nodes/logs        — push batched log lines
POST /api/compute/nodes/drain       — stop accepting new jobs
POST /api/compute/nodes/list        — list nodes in your business
POST /api/compute/nodes/rotate-key  — rotate a node's API key

Artifacts

POST /api/compute/jobs/artifacts/presign-upload    — browser-flow upload URL (JWT)
POST /api/compute/jobs/artifacts/presign-download  — browser-flow download URL (JWT)
PUT  /api/compute/artifacts/upload/{jobId}/{id}    — agent direct upload (URL-is-auth)
GET  /api/compute/artifacts/download/{jobId}/{id}  — direct download (URL-is-auth)

API keys

POST /api/compute/api-keys/list     — keys for the logged-in user
POST /api/compute/api-keys/create   — mint a new user API key
POST /api/compute/api-keys/revoke   — revoke a key by id

Billing

POST /api/compute/billing/plans/list       — available subscription plans
POST /api/compute/billing/subscription     — current user's subscription
POST /api/compute/billing/checkout/create  — start a Stripe checkout flow

Rate limits

Per user: 1 000 requests / minute burst, 30 000 / hour sustained. Per agent API key: quotas set on the key itself (maxJobsPerHour, maxConcurrentJobs, allowedJobTypes).

429 Too Many Requests responses include Retry-After in seconds.

Idempotency

Job submission is not idempotent server-side — re-submitting creates a new job. If you need at-most-once semantics, store the submitted job_id on your side and check /jobs/retrieve before retrying.

Heartbeat, poll, and log-push are idempotent.

Errors

Failures return a consistent envelope:

{
  "status": "ERROR",
  "message": "Human-readable reason",
  "payload": null
}

Common status strings: SUCCESS, ERROR, NO_DATA, UNAUTHORIZED, FORBIDDEN, RATE_LIMITED.

Deeper reference

For the Kotlin / Swift / TypeScript bindings on top of this surface, see sdk. For OpenAPI / Postman exports generated from the server source of truth, see the tanvrit/server repository's docs/postman/tanvrit-server.postman_collection.json.