Direct HTTP access to inference.sh.
Base URL
1https://api.inference.shPath 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_keyContent Type
1Content-Type: application/jsonAPI 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 1 (default) | Version 2 (X-API-Version: 2) | |
|---|---|---|
| Success body | Wrapped: { "success": true, "status": 200, "data": { ... } } | Bare resource DTO (same fields as data in v1) |
| Error body | Wrapped: { "success": false, "status": 4xx, "error": { "code", "message" } } | RFC 9457 application/problem+json |
| Requirements (412) | { "satisfied": false, "errors": [...] } | Same (not wrapped) |
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).
Without the header, errors use the version 1 wrapper with error.code, error.message, and optionally error.suggestions (array of suggested namespace/name refs on some not_found responses, such as unknown app lookups).
Error Codes
| Code | HTTP | Description |
|---|---|---|
unauthorized | 401 | Invalid or missing API key |
forbidden | 403 | Insufficient permissions |
not_found | 404 | Resource not found |
invalid_request | 400 | Malformed request |
rate_limited | 429 | Too many requests |
internal_error | 500 | Server error |
Billing and plan limits
Two kinds of billing errors can block API calls:
| Kind | Typical codes | What to check |
|---|---|---|
| Plan limits | limit_exceeded (402), feature_not_available (403) | Subscription tier caps — API keys, storage, concurrent tasks, feature flags |
| Prepaid balance | payment_required (402) | Credits for task and agent runs |
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.sh app, entitlement errors with upgrade_available: true open an upgrade modal instead of only surfacing a toast:
| API error | Modal |
|---|---|
limit_exceeded or feature_not_available | Upgrade modal — lists self-serve plans above your current tier |
payment_required (402 without upgrade_available) | Top-up modal — add prepaid credits |
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.
Direct links: Pricing (browse plans) · Billing (credits) · Subscription (manage plan)
Rate Limits
| Endpoint | Limit |
|---|---|
| Run task | 100/minute |
| Get task | 1000/minute |
| Upload file | 50/minute |
Response headers:
1X-RateLimit-Remaining: 952X-RateLimit-Reset: 16400000003Retry-After: 60Some 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.jsonOpenAPI 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.
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