Docs / API

Compute API reference

The Vikshep Compute API accepts physics analysis jobs, returns job IDs for async polling, and streams results as JSON. All endpoints require a Bearer API key issued through your account.

Base URL: https://api.vikshep.dev

Authentication

Include your API key in every request as an HTTP Bearer token:

Authorization: Bearer vsk_your_key_here

Keys begin with vsk_ and are shown once at creation. A revoked or unknown key returns 401 UNKNOWN_KEY or 401 KEY_REVOKED.

Job endpoints

POST /api/jobs — Submit a job

Submit a recipe for execution. Returns immediately with a job ID.

curl -X POST https://api.vikshep.dev/api/jobs \
  -H "Authorization: Bearer vsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe": "recipe_tag",
    "input": {
      "manifest_path": "/data/manifest.json",
      "label": "is_signal",
      "protect": "jet_mass"
    },
    "gpu_seconds_requested": 120
  }'

Request body:

Field	Type	Required	Description
recipe	string	yes	One of the supported op names (see table below)
input	object	yes	Recipe-specific parameters
gpu_seconds_requested	number	no	Requested budget (default: 60). Clamped to remaining quota.

Response (202 Accepted):

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "recipe": "recipe_tag",
  "message": "Job queued. Poll /api/jobs/[id] for status."
}

GET /api/jobs/[id] — Poll job status

curl https://api.vikshep.dev/api/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer vsk_your_key"

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "recipe": "recipe_tag",
  "status": "done",
  "result": {
    "output": { "auc": 0.97, "dcorr2": 0.001, ... },
    "wall_clock_seconds": 14.2
  },
  "gpu_seconds_used": 15,
  "queued_at": "2026-09-10T09:00:00Z",
  "finished_at": "2026-09-10T09:00:15Z"
}

status transitions: queued → running → done or failed. Poll every 2–5 seconds.

Supported recipes (CPU mode)

GPU-accelerated scattering ops are pending hardware provisioning. CPU recipe ops are available now.

Recipe	Status	Required input fields	Description
ingest_g4	available	csv_path, schema? (default: komal_v1)	Ingest Geant4 CSV → manifest.json
recipe_tag	available	manifest_path, label, protect, weights?, lambda?	Particle tagging with DisCo decorrelation
recipe_calibrate	available	manifest_path, target	Detector calibration regression
scatter	GPU pending	—	Wavelet-scattering feature extraction (GPU required)
sw1-graph	GPU pending	—	SW1 graph pipeline (GPU required)

Error vocabulary

Status	error code	Meaning
401	MISSING_KEY	No Authorization header
401	UNKNOWN_KEY	Key not found in keystore
401	KEY_REVOKED	Key has been revoked
402	PAYMENT_REQUIRED	No active entitlement or quota exhausted
402	TRIAL_BUDGET_EXHAUSTED	Trial GPU-seconds depleted
400	UNSUPPORTED_OP	Recipe not in CPU allowlist (GPU_PENDING or UNKNOWN_RECIPE)
400	MISSING_FIELD	Required request field absent
429	QUOTA_EXHAUSTED	Per-org rate limit exceeded
503	KV_UNREACHABLE	Entitlement cache unavailable; request denied (fail-closed)

Quota semantics

GPU-seconds are billed by actual wall-clock compute time, clamped to the budget requested in the job. Budget is clamped to your remaining quota at submit time — if remaining is 30s and you request 60s, the job runs with a 30s budget (and the job succeeds if it finishes within 30s).

Trial quota: 900 GPU-seconds per verified email, shared across all trial jobs. A running job is allowed to complete when the budget expires; the next submitted job receives 402 TRIAL_BUDGET_EXHAUSTED.

Next steps

Quickstart →Pricing & trial →