REST API reference.

Every request authenticates with a Bearer token. Mint one at /settings/api-keys and store the secret in your environment — it's shown once.

Format: dr_live_<64-char hex> in production; dr_test_<64-char hex> elsewhere. Scopes constrain what a key can do — pick the narrowest set that meets your use case (read, generate, write, admin).

bashcurl https://13-204-237-151.nip.io/api/health \
  -H "Authorization: Bearer dr_live_<your-key>"

All endpoints return a JSON envelope of the form { ok: boolean, ... }. Errors carry a short machine-readable string in error and, for validation failures, an issues array from zod.

json// 422 validation
{
  "ok": false,
  "error": "Validation failed",
  "issues": [{ "path": ["uploadKey"], "message": "Required" }]
}

// 402 insufficient credits
{ "ok": false, "error": "Insufficient credits", "required": 5 }

// 429 rate-limited
{ "ok": false, "error": "Too many requests" }  // Retry-After header

Rate limits are per-user per-namespace: 30 generate/min, 5 key-creates/5min, 10 webhook-creates/5min. Above the limit you get HTTP 429 with a Retry-After header in seconds.

Batch generate

bashcurl https://13-204-237-151.nip.io/api/generate/batch \
  -H "Authorization: Bearer dr_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadKeys": ["uploads/a.png", "uploads/b.png", "uploads/c.png"],
    "uploadMime": "image/png",
    "modeSlug":   "studio_default",
    "brandId":    "b1c4..."
  }'

# → 202
{ "ok": true, "generationIds": ["g-1...", "g-2...", "g-3..."] }

Upload

bashcurl https://13-204-237-151.nip.io/api/upload \
  -H "Authorization: Bearer dr_live_<your-key>" \
  -F "file=@./product.jpg;type=image/jpeg"

# → 200
{ "ok": true, "key": "uploads/...", "url": "https://...", "mime": "image/jpeg" }

Get a generation

bashcurl https://13-204-237-151.nip.io/api/generations/g-abc... \
  -H "Authorization: Bearer dr_live_<your-key>"

# → 200
{
  "ok": true,
  "gen": { "id": "g-abc...", "status": "shipped", "modeSlug": "studio_default", ... },
  "outputs": [{ "id": "o-...", "url": "https://...", "fidelityScore": 87, "verdict": "ship" }],
  "verification": { "totalScore": 87, "deltaE": 2.4, ... }
}

Brands

bashcurl https://13-204-237-151.nip.io/api/brands \
  -H "Authorization: Bearer dr_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shabari Naturals", "category": "Ayurvedic skincare" }'

Mistakes (AI Brain)

bashcurl https://13-204-237-151.nip.io/api/brands/b1c4.../mistakes \
  -H "Authorization: Bearer dr_live_<your-key>" \
  -F "description=Logo color drifted too dark" \
  -F "kind=logo_color" \
  -F "x=42" \
  -F "y=71"

API key management

Requires admin scope.

bashcurl https://13-204-237-151.nip.io/api/keys \
  -H "Authorization: Bearer dr_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-pipeline", "scopes": ["read", "generate"] }'

# → 201
{ "ok": true, "key": { "id": "...", "secret": "dr_live_..." } }

Webhook subscriptions

Requires admin scope.

bashcurl https://13-204-237-151.nip.io/api/webhooks \
  -H "Authorization: Bearer dr_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://your-domain.example/drishti-webhook",
    "events": ["generation.shipped", "generation.refunded"]
  }'

bashcurl https://13-204-237-151.nip.io/api/webhooks/<id>/test \
  -H "Authorization: Bearer dr_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"event":"generation.shipped"}'

Drishti POSTs JSON to your endpoint with three headers you care about:

• X-Drishti-Event — the event name (e.g. generation.shipped).
• X-Drishti-Event-Id — stable id; use for idempotent dedup.
• X-Drishti-Signature — t=<unix>,v1=<hex>. Verify with HMAC SHA-256 of `${t}.${rawBody}`.

Verifying a signature (Node)

tsimport { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody: string, header: string, secret: string): boolean {
  const m = /^t=(\d+),v1=([a-f0-9]+)$/.test(header.trim())
    ? header.trim().match(/^t=(\d+),v1=([a-f0-9]+)$/)
    : null;
  if (!m) return false;
  const ts = Number(m[1]), sig = m[2];
  // Reject anything older than 5 minutes to defeat replay attacks.
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(sig, "hex"), Buffer.from(expected, "hex"));
}

Event payloads

json// generation.shipped (warn=true when verdict='warn-ship')
{
  "event": "generation.shipped",
  "workspaceId": "ws-...",
  "payload": {
    "generationId": "g-...",
    "modeSlug": "studio_default",
    "outputs": [{ "outputId": "o-...", "verdict": "ship", "fidelityScore": 87 }],
    "verdict": "ship",
    "warn": false
  },
  "timestamp": "2026-05-20T08:14:00Z"
}

// generation.refunded
{
  "event": "generation.refunded",
  "payload": {
    "generationId": "g-...",
    "modeSlug": "studio_default",
    "rejectedOutputs": [{ "outputId": "o-...", "verdict": "refund", "fidelityScore": 62 }]
  }
}

// generation.failed (permanent error)
{
  "event": "generation.failed",
  "payload": {
    "generationId": "g-...",
    "modeSlug": "studio_default",
    "failureReason": "Gemini blocked: safety policy",
    "transient": false
  }
}

// brand.created
{
  "event": "brand.created",
  "payload": { "brandId": "b-...", "slug": "shabari-naturals-ab3", "name": "Shabari Naturals", "category": "Ayurvedic skincare" }
}

// brand.mistake.added
{
  "event": "brand.mistake.added",
  "payload": { "brandId": "b-...", "mistakeId": "m-...", "kind": "logo_color", "description": "Logo drifted too dark...", "hasEvidence": true }
}

Delivery retries: 5 attempts at 1s, 3s, 9s, 27s, 81s. At 10+ accumulated failures we stop delivering until you reset via /settings/webhooks.

MCP — full 14-tool surface

The 14 MCP tools all sit behind a single JSON-RPC endpoint at https://13-204-237-151.nip.io/api/mcp. Six of them have dedicated REST endpoints above; the remaining eight (verify_image, brand_vault_set, estimate_cost, fix_one_thing, marketplace_export, batch_generate, recall_recipe, mistake_check) are MCP-only today.

Enumerate the catalogue

bashcurl https://13-204-237-151.nip.io/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# → {"jsonrpc":"2.0","id":1,"result":{"tools":[...14 entries...]}}

tools/list is open — no Authorization header required. Useful for clients that introspect before pasting a key.

Call a tool (Bearer required)

bashcurl https://13-204-237-151.nip.io/api/mcp \
  -H "Authorization: Bearer dr_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "estimate_cost",
      "arguments": { "modeSlug": "marketplace_export", "count": 5 }
    }
  }'

# → result.content[0].text is a JSON string with the tool's payload.

Error codes

• -32001 Unauthorized — missing / invalid Bearer key
• -32002 Rate-limited — 60/min/tool per workspace
• -32003 Insufficient credits — top up at /billing#topup
• -32601 Method not found — likely a tool name typo
• -32602 Invalid params — fails zod shape; error.data carries the path

SDK quick start

The official @drishti/sdk package wraps every endpoint above plus the MCP catalogue. Zero runtime deps; works on Node 18+, Bun, Deno, and browsers.

bashnpm install @drishti/sdk

tsimport { Drishti, McpError } from "@drishti/sdk";

const dr = new Drishti({ apiKey: process.env.DRISHTI_API_KEY! });

// REST: upload → generate → wait for verdict
const file = await fetch("./product.jpg").then((r) => r.blob());
const { key, mime } = await dr.upload(file, "image/jpeg", "product.jpg");
const { generationId } = await dr.generate({
  uploadKey: key,
  uploadMime: mime,
  modeSlug: "studio_default",
});
const done = await dr.waitForGeneration(generationId);

// MCP: any of the 14 tools via the JSON-RPC passthrough
try {
  const est = await dr.mcpCall("estimate_cost", {
    modeSlug: "marketplace_export",
    count: 5,
  });
  console.log(est.content[0].text);
} catch (e) {
  if (e instanceof McpError && e.code === -32003) {
    console.error("Out of credits");
  }
}

Full method reference + lifecycle examples in the npm package README. The SDK ships separate @drishti/sdk/webhooks subpath for the signature verifier so verify-only edge functions get a smaller bundle.