# API & SDK Overview

> Programmatic access for developers.

**URL:** https://inference.sh/docs/api/overview
**Last updated:** 2026-10-18

---

**Programmatic access for developers.**

Everything in the web app is available via API. Run apps, execute flows, and interact with agents from your own code.

For direct HTTP access, see [REST API overview](/docs/api/rest/overview) — including the response envelope, RFC 9457 errors, and the [OpenAPI route catalog](/docs/api/rest/overview#openapi) at `GET /openapi.json`.

---

## Quick Start

### 1. Get an API Key

1. Go to [settings → workspace → api keys](https://app.inference.sh/settings/team/keys)
2. Click **Create API Key**
3. Copy your key (starts with `inf_`)

### 2. Install an SDK

<div data-type="codegroup">

```python
pip install inferencesh

# With async support
pip install inferencesh[async]
```

```typescript
npm install @inferencesh/sdk
// or: yarn add @inferencesh/sdk
// or: pnpm add @inferencesh/sdk
```

```swift
// Package.swift
.package(url: "https://github.com/inference-sh/sdk-swift", from: "0.1.0")
// target dependency: .product(name: "InferenceSDK", package: "sdk-swift")
```

</div>

### 3. Run Your First App

<div data-type="codegroup">

```python
from inferencesh import inference

client = inference(api_key="inf_your_key")

result = client.run({
    "app": "infsh/echo",
    "input": {"message": "Hello from the API!"}
})

print(result["output"])
```

```typescript
import { inference } from '@inferencesh/sdk';

const client = inference({ apiKey: 'inf_your_key' });

const result = await client.run({
  app: 'infsh/echo',
  input: { message: 'Hello from the API!' }
});

console.log(result.output);
```

```swift
import InferenceSDK

let client = InferenceClient(apiKey: "inf_your_key")

let task = try await client.tasks.run(ApiAppRunRequest(
    app: "infsh/echo",
    input: ["message": "Hello from the API!"]
))

print(task.output)
```

</div>

---

## What's Available?

### Building Apps

→ [Extend overview](/docs/extend/overview) — CLI setup, app code, deploy, and related guides

### SDK Reference
Full SDK documentation with tabbed Python/JavaScript examples (Swift where supported).

- [**SDK Overview**](/docs/api/sdk/overview) — Installation, quick start
- [**JavaScript SDK**](/docs/api/sdk-javascript) — TypeScript/JavaScript reference
- [**Python SDK**](/docs/api/sdk-python) — Python reference
- [**Swift SDK**](/docs/api/sdk-swift) — Swift reference (iOS, macOS, Linux)
- [**Running Apps**](/docs/api/sdk/running-apps) — Execute apps programmatically
- [**Streaming**](/docs/api/sdk/streaming) — Real-time progress updates
- [**Files**](/docs/api/sdk/files) — Upload and download files

### Agent SDK
Build headless AI agents with tools and multi-turn conversations.

- [**Agent Overview**](/docs/api/agent/overview) — Agent SDK introduction
- [**Template Agents**](/docs/api/agent/template) — Use existing agents
- [**Ad-hoc Agents**](/docs/api/agent/adhoc) — Create agents programmatically
- [**Building Tools**](/docs/api/agent/tools) — Define custom tools

### REST API
Use any language with the REST API.

- [**REST Overview**](/docs/api/rest/overview) — Base URL, response format, errors, OpenAPI catalog
- [**Entitlements**](/docs/api/rest/entitlements) — Plan limits, usage (`GET /entitlements/usage`), and feature flags
- [**Tasks**](/docs/api/rest/tasks) — Run apps, status, webhooks, cancellation
- [**Flow runs**](/docs/api/rest/flow-runs) — Execute saved flows programmatically
- [**Remotes**](/docs/api/rest/remotes) — Register outbound daemons and opt in to command execution
- [**Exec runs**](/docs/api/rest/exec-runs) — Dispatch commands to remotes and stream output
- [**Apps**](/docs/api/rest/apps) — App metadata, versions, set active version
- [**Agents**](/docs/api/rest/agents) — Chat sessions and structured `output`
- [**Search**](/docs/api/rest/search) — Discover apps, skills, and knowledge
- [**Instance types**](/docs/api/rest/instances) — Public GPU catalog, hourly pricing, and daily price history
- [**Skills**](/docs/api/rest/skills) · [**Knowledge**](/docs/api/rest/knowledge) — Registry and knowledge entries
- [**Streaming**](/docs/api/rest/streaming) — SSE for tasks and agent chats
- [**Billing**](/docs/api/rest/billing) · [**Subscription**](/docs/api/rest/subscription) — Balance top-ups and plan management

---

## Response format

Every JSON response is `{ "data": ..., "messages": [...] }` and errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details. The SDKs unwrap `data`. See [REST overview — response format](/docs/api/rest/overview#response-format).

---

## Authentication

All API calls require an API key in the header:

<div data-type="codegroup">

```python
from inferencesh import inference

client = inference(api_key="inf_your_key")
# Or read INFERENCE_API_KEY from the environment:
# client = inference()
```

```typescript
import { inference } from '@inferencesh/sdk';

const client = inference({ apiKey: 'inf_your_key' });
// Or use environment variable:
// const client = inference({ apiKey: process.env.INFERENCE_API_KEY });
```

```swift
import InferenceSDK

let client = InferenceClient(apiKey: "inf_your_key")
// Or use environment variable:
// let client = InferenceClient(apiKey: ProcessInfo.processInfo.environment["INFERENCE_API_KEY"] ?? "")
```

```bash
curl https://api.inference.sh/apps/run \
  -H "Authorization: Bearer inf_your_key"
```

</div>

→ [Full Authentication Guide](/docs/api/authentication)

---

## Task Status Codes

Numeric status codes are returned on task objects and webhook payloads. Common values:

| Status | Code | Meaning |
|--------|------|---------|
| Queued | 2 | Waiting for worker |
| Running | 7 | Executing |
| Completed | 10 | Done |
| Failed | 11 | Error occurred |
| Cancelled | 12 | Cancelled |
| Rejected | 13 | Refused before running: the workspace has no balance or no payment method. The input is kept; the run can be retried. |

→ [Full status code list](/docs/api/rest/tasks#task-status-codes)

---

## Rate Limits

| Endpoint | Limit |
|----------|-------|
| Run task | 100/minute |
| Get task | 1000/minute |
| Upload file | 50/minute |