API reference
Ten endpoints. The catalog is the contract — everything else reads from it.
Base URL https://skylarklabs.ai/api/models. Authentication is a bearer token:
Authorization: Bearer $SKYLARK_API_KEY.
There is no OpenAPI document. https://skylarklabs.ai/api/models/sdk/curl is the de-facto spec —
it is executable, it is served by the same build you are calling, and it is
what this page is checked against.
Catalog
GET /api/models/catalog
Every model, its classes, frame costs and the service's limits. No auth.
Returns version, aiStatus, limits, sdk[], solutions[].
This is the contract. Read model ids, per-call frame costs and every limit from here rather than hard-coding them — it is why the Models and Limits pages cannot go stale.
GET /api/models/healthz
Liveness, uptime and upstream status. No auth.
Returns status, uptimeSec, enabled, ai, solutions.
GET /api/models/sdk/{lang}
The client source for one language, as served by this build. No auth.
| Param | Type | Description | |
|---|---|---|---|
lang | string | Required | curl · python · node · ts · browser |
Returns the file, inline.
Sessions
POST /api/models/session
Mint a browser session token. No auth.
| Param | Type | Description | |
|---|---|---|---|
deviceId | uuid v4 | Required | A stable per-browser id. A fairness key, not a credential. |
turnstileToken | string | Optional | Required only when the service has a challenge configured. |
Returns token, credits, expiresAt, deviceFramesLeft, networkFramesLeft.
Keys
GET /api/models/key
What is left on the presented token. Bearer.
Returns audience, remaining, hourRemaining, expiresAt.
Costs no frames and touches no model, which is what makes it safe to call on startup — otherwise the cheapest way to check a key would be to spend one.
POST /api/models/sdk-key
Exchange a browser session for a trial SDK key. Bearer — a browser session only.
Returns key, frames, expiresAt, notice.
Inference
POST /api/models/infer/image
Run a model on one image. Synchronous. Bearer.
| Param | Type | Description | |
|---|---|---|---|
solution | string | Required | A solution id from the catalog. |
file | file | Required | multipart/form-data. |
Returns detections[], image, stats, credits.
POST /api/models/infer/video
Submit a clip. Returns 202 with a job to poll. Bearer.
| Param | Type | Description | |
|---|---|---|---|
solution | string | Required | A solution id from the catalog. |
file | file | Required | multipart/form-data. |
Returns jobId, status, queuePosition, pollUrl, pollIntervalMs, credits.
GET /api/models/jobs/{id}
Poll a video job. Bearer — the token that created the job.
Returns status, progress, queuePosition, pollIntervalMs, result?, error?.
Honour pollIntervalMs. It rises with the queue, so respecting it is how a
client shares backpressure instead of adding to it. Note a failed job reports
its failure in error inside a 200 — see Errors.
DELETE /api/models/jobs/{id}
Cancel a job and release its slot on the detection server. Bearer — the token that created the job.
Returns an acknowledgement.