REST API

Direct HTTP access to inference shell.

Base URL

1https://api.inference.sh

Path prefix

All routes also work under an optional /v1/ prefix. The prefix is stripped internally — handlers are registered at the root path.

1# Equivalent requests2curl https://api.inference.sh/tasks/task_abc123 -H "Authorization: Bearer inf_your_key"3curl https://api.inference.sh/v1/tasks/task_abc123 -H "Authorization: Bearer inf_your_key"

Use whichever form matches your client or OpenAPI tooling. Official SDKs and the belt/infsh CLIs call the root paths (without /v1/).

Authentication

All requests require an API key in the Authorization header:

1Authorization: Bearer inf_your_api_key

Content Type

1Content-Type: application/json

API version

Send X-API-Version: 2 to use the modern response format. The official JavaScript and Python SDKs, plus the belt / infsh CLIs, send this header automatically on API calls.

Version 2 success example (task from POST /run):

1{2  "id": "task_abc123",3  "status": 10,4  "output": { "image": { "uri": "https://..." } }5}

Version 2 error example (401):

1{2  "type": "https://api.inference.sh/errors/unauthorized",3  "title": "Unauthorized",4  "status": 401,5  "detail": "Invalid or missing API key"6}

Version 1 error example (same request without the header):

1{2  "success": false,3  "status": 401,4  "error": {5    "code": "unauthorized",6    "message": "Invalid or missing API key"7  }8}

REST examples in this section use version 2 unless noted otherwise. Add the header to curl:

1curl https://api.inference.sh/tasks/task_abc123 \2  -H "Authorization: Bearer inf_your_key" \3  -H "X-API-Version: 2"

Error Responses

With X-API-Version: 2, errors use Content-Type: application/problem+json and the type, title, status, and detail fields shown above. The type URI ends with the error code (for example .../errors/not_found).

Some errors include an optional meta extension member with structured context — for example entitlement errors (limit_exceeded, feature_not_available) attach resource, limit, current, upgrade_available, and optional addon plan fields. See Entitlements API — Error metadata.

Without the header, errors use the version 1 wrapper with error.code, error.message, optional error.meta (same structured fields as version 2), and optionally error.suggestions (array of suggested namespace/name refs on some not_found responses, such as unknown app lookups).

Error Codes

Billing and plan limits

Two kinds of billing errors can block API calls:

Inspect current usage programmatically with GET /entitlements/usage. List entitlement rows (limits and sources) with GET /entitlements. See Entitlements API for response formats and error metadata.

Workspace modals

In the inference shell app, entitlement errors with upgrade_available: true open an upgrade modal instead of only surfacing a toast:

The upgrade modal shows the API detail message (or which resource requires a higher plan). For limit_exceeded, it also shows current usage / plan cap (for example 3 / 5) when the cap is greater than zero. A 0 cap means the feature is disabled on your tier — the modal omits a usage line instead of showing 0 / 0.

Each listed plan shows monthly price, included credits, and key limits. The recommended badge marks the cheapest plan that resolves the blocked resource (unlimited, a higher numeric cap, or an enabled boolean feature). Select a plan or View all plans to open Subscription.

When the error includes addon_plan_id, the modal shows a single add-on card with a subscribe - $X/mo button that routes to Add-ons — the same purchase flow as the add-ons settings page (Stripe Checkout via POST /subscription/addon). Most add-ons do not require a base subscription; some set required_plan_ids on the plan.

Direct links: Pricing (browse plans) · Billing (credits) · Subscription (manage plan) · Add-ons (purchase add-ons)

Rate Limits

Response headers:

1X-RateLimit-Remaining: 952X-RateLimit-Reset: 16400000003Retry-After: 60

Some endpoints (for example magic link send when throttled by IP) return HTTP 429 with a Retry-After header (whole seconds). Browser clients can read it — the API exposes Retry-After in CORS Access-Control-Expose-Headers.

OpenAPI

Download the generated route catalog:

1GET https://api.inference.sh/openapi.json

OpenAPI 3.1 document listing public paths, methods, and schemas. Useful for client generation and discovering routes not yet covered in these guides. No authentication required.

Cursor pagination

Most list endpoints (GET /tasks, GET /skills, POST /apps/list, GET /chats/:id/messages, and others) use the same cursor-list shape. Send parameters as query strings on GET or in a JSON body on POST …/list.

Response shape

Responses may include RFC 8288 Link headers (rel="next", rel="prev") with the same cursors.

Full dumps (limit=-1)

Pass limit=-1 on any cursor-paginated list endpoint to skip pagination and return matching rows in one response (capped at 10,000 rows). Sort and filters still apply; cursor and direction are ignored. has_next is false — treat items as the complete result set when the match count is under the cap.

Use this for exports, migrations, or debugging on smaller datasets. Prefer normal cursor pagination for UI scroll-back and tables that may exceed 10,000 rows.

1curl "https://api.inference.sh/tasks?limit=-1&filters=%5B%7B%22field%22%3A%22status%22%2C%22operator%22%3A%22eq%22%2C%22value%22%3A10%7D%5D" \2  -H "Authorization: Bearer inf_your_key" \3  -H "X-API-Version: 2"

Endpoints

• Tasks — Run apps, status, logs, timings, telemetry, cancellation, webhooks, cost
• Engines — Private engine list, drain, update, stop
• Files — Upload files
• Agents — Agent chat API
• Publications — Publish agents for embedding (POST /publications)
• Embed — Anonymous chat API for published agents
• Triggers — Cron and webhook automation (run agents, apps, flows)
• Skills — Manage and access skills
• Knowledge — Manage knowledge entries
• Pages — Read CMS pages (docs, blog, landing pages)
• Search — Search apps, skills, knowledge, and pages
• Entitlements — Plan limits, usage, and feature flags
• Streaming — SSE endpoints
• Billing · Subscription — Credits and plan management
• Magic link sign-in · Device authorization — Workspace and CLI login