1 · Auth + scopes
Every request carries x-api-key: <your-key>. Keys are minted at one of three endpoints:
- Staff — commandcenter — admin.insightsbyomkar.com/products/urja (role-based, TOTP-gated). Pick a scope preset, set owner + TTL, mint. Raw JWT displayed once. Any staff profile with an owner / operator / support role qualifies.
- Customer self-serve — studio.insightsbyomkar.com/account/api-keys (signed-in users view, rotate, and revoke their own keys).
- Programmatic —
POST urja.insightsbyomkar.com/api/internal/provision-keywithx-signatureHMAC of the body againstSSO_SHARED_SECRET, plus a{ nonce, issuedAt }envelope. For server callers (Stripe webhook bridge, CI jobs).
Keys carry one or more of these scopes:
| Scope | Grants |
|---|---|
critic:v1 | Umbrella — satisfies all critic:v1:* requirements. |
critic:v1:read | GET /rubrics, /rubrics/[id], /references, /references/[id]. No billable calls. |
critic:v1:use | POST /critique. Metered / billable. |
2 · Response envelope
Every 2xx response shares a top-level meta block plus the endpoint-specific payload. Rate-limit + Retry-After headers follow Stripe conventions.
{
"meta": {
"engine": "insights-by-omkar-engine",
"engineVersion": "7.15.1",
"criticApiVersion": "1.0.0",
"criticApiStability": "beta",
"computedAt": "2026-04-19T13:22:00.000Z"
},
...payload
}3 · POST /critique
https://urja.insightsbyomkar.com/api/v1/critic/critique · Scope: critic:v1:use · Metered.
Request body
{
"output": { "kind": "image-url", "url": "https://your-cdn/render.png" },
// or:
"output": { "kind": "image-data", "dataUri": "data:image/png;base64,iVBORw0KG..." },
"rubricId": "character-figure", // see GET /rubrics
"referenceSetId": "great-dane", // see GET /references
"subjectHint": "optional ≤ 500 chars — 'the renderer aimed at: X'",
"providerId": "openai/gpt-4o", // optional; default
"timeoutMs": 60000, // optional; [10000, 120000]
"useCache": true // optional; false forces fresh
}Response
{
"meta": { ..., "elapsedMs": 14230 },
"critique": {
"rubricId": "character-figure",
"rubricVersion": "1.0.0",
"referenceSetId": "great-dane",
"referenceSetVersion":"1.0.0",
"axisScores": [
{
"axisId": "proportion-fidelity",
"score": 6, // 0-10, integers or .5
"anchorBand": "5→8",
"reasoning": "Ratios approximately right in head but visibly off in body/leg..."
},
... // one per rubric axis
],
"weightedTotal": 5.85, // rubric.axes weighted sum
"failings": [
{
"title": "muzzle too short",
"axisId": "proportion-fidelity",
"landmarkId": "muzzle-skull-ratio", // optional
"severity": 4, // 1-5
"proposedFix": "increase muzzleLengthRatio from ~0.30 to ~0.50",
"autoApplicable": true
},
... // ordered severity desc
],
"narrative": "2-4 paragraphs ...",
"computedAt": "...",
"producedBy": "openai/gpt-4o" // anonymised provider id
},
"cache": { "hit": false, "key": "sha256..." },
"usage": { "costUsd": 0.0124, "tokens": { "input": 1842, "output": 512 } },
"provider": "openai/gpt-4o"
}Rules
- Image limits: data URIs capped at 20MB; URL images must be publicly reachable.
- Cache keys include rubric version, reference-set version, provider id, and the output fingerprint. A re-render with the same seeds hits cache; a provider switch does not.
- Severity 5 ≈ wrong subject entirely. Severity 1 ≈ nit. Usually 3–8 failings per critique.
- autoApplicable:
truemeans the fix is a numeric parameter tweak.falsemeans structural (add a stop, restructure anatomy). Your pipeline decides what to apply automatically.
4 · GET /rubrics
https://urja.insightsbyomkar.com/api/v1/critic/rubrics · Scope: critic:v1:read
Returns summaries for every rubric currently shipping.
{
"meta": { ..., "criticApiStability": "beta" },
"rubrics": [
{
"id": "character-figure",
"name": "Character Figure (v1)",
"version": "1.0.0",
"subjectKinds": ["character-figure"],
"axisCount": 7,
"stability": "beta"
},
{
"id": "ambient-effect",
"name": "Ambient Effect (v1)",
"version": "1.0.0",
"subjectKinds": ["ambient-effect"],
"axisCount": 5,
"stability": "beta"
}
]
}5 · GET /rubrics/[id]
https://urja.insightsbyomkar.com/api/v1/critic/rubrics/character-figure
Full rubric definition — prompt framing, every axis (name, weight, anchor descriptions at 2/5/8/10, guidance), global guidance block. Use this to explain an axis score in your UI, or to re-implement the weighted total locally for previews.
6 · GET /references
https://urja.insightsbyomkar.com/api/v1/critic/references · Scope: critic:v1:read
Summary list of every reference set.
{
"meta": { ... },
"referenceSets": [
{
"id": "great-dane",
"name": "Great Dane — canonical breed references",
"subjectKind": "character-figure",
"version": "1.0.0",
"lastReviewedAt": "2026-04-19",
"referenceCount": 3,
"compatibleRubrics": ["character-figure"]
}
]
}7 · GET /references/[id]
https://urja.insightsbyomkar.com/api/v1/critic/references/great-dane
Full reference-set metadata including license blocks, landmark specifications with target ranges, and text-reference contents. Image bytes are not embedded — they reference imagePath relative to the reference root.
8 · Errors
Errors follow the engine’s ApiError envelope with an added details.criticCode carrying the critic-specific code for client handling without message parsing.
| criticCode | HTTP | Meaning |
|---|---|---|
UNKNOWN_RUBRIC | 404 | The rubricId isn’t registered. |
UNKNOWN_REFERENCE_SET | 404 | The referenceSetId isn’t registered. |
INCOMPATIBLE_RUBRIC_REFERENCE | 400 | Pair isn’t compatible (e.g. ambient-effect rubric with great-dane refs). |
MISSING_OUTPUT | 400 | No output field or malformed shape. |
UNSUPPORTED_OUTPUT_KIND | 400 | output.kind neither image-url nor image-data. |
PROVIDER_UNAVAILABLE | 503 | Requested providerId isn’t registered or configured. |
ENV_MISCONFIGURED | 503 | Provider env var missing server-side (ops issue). |
PROVIDER_TIMEOUT | 504 | Critic call exceeded timeoutMs. |
PROVIDER_ERROR | 502 | Upstream vision model returned an error. |
PARSE_ERROR | 502 | Provider returned malformed JSON that didn’t match the schema. |
INTERNAL | 500 | Anything else. |
9 · Versioning + stability
- Track:
critic-v1. Lives under/api/v1/critic/*for the life of this major. - Additive changes (new rubric, new reference set, new axis) ship as minor bumps of the rubric / set / API — never break a v1 client.
- Breaking changes ship under
/api/v2/critic/*with a 6-month deprecation window on v1. - Stability is advertised per-rubric and per-endpoint.
betameans contract is close to stable; we notify customers 30 days before any breaking change within v1. - Key scopes pin to
critic:v1— v2 requires customer opt-in during migration.
Full policy: see docs/API-VERSIONING.md in the engine repo. Changelog: docs/changelog/critic-v1.md.
10 · Providers + independence
Default critic provider: openai/gpt-4o. The provider id is part of the cache key, so a critique from provider A and a critique from provider B for the same image and rubric are stored separately — provider swaps never alias.
Clients MAY override with providerId in the request. Clients MUST NOT assume which model produced a critique — the public contract only guarantees the anonymised provider id (e.g. openai/gpt-4o, not gpt-4o-2024-11-20).
Independence rule.The provider used for critique must not be the provider used for generation. This is enforced by policy, not by the API — but it’s the whole point. A critic that shares a model with the generator is a toy; a critic on a different model is an art director.