Run published agents from external sites without API keys. Requests go to the /embed route group on the API host.
The hosted chat UI at https://app.inference.sh/embed/agents/{namespace}/{name} uses these endpoints internally. Build your own UI with the same API.
→ Publishing and embedding agents — workspace setup, origins, themes, and iframe snippets
→ Publications API — create and manage publications (POST /publications, etc.)
Base URL
1https://api.inference.sh/embedNo Authorization header is required. The API uses anonymous access with credentials cookies when present.
Send X-API-Version: 2 for bare JSON responses (same as the main REST API).
Origin validation
Published agents validate the request Origin header against the publication's allowed_origins:
allowed_origins | Behavior |
|---|---|
| Empty | All origins allowed |
| List of URLs | Origin must match an entry exactly, or the list may include * |
| Mismatch | 403 forbidden — origin not allowed |
Configure origins in the workspace Publish tab before calling the embed API from a browser.
Get published agent info
GET /embed/agents/{namespace}/{name}
Returns agent metadata and optional publication theme for styling your UI.
Response
| Field | Description |
|---|---|
name | Agent display name |
namespace, name | Agent ref components |
version | Active version (description, example prompts, etc.) |
theme | Optional light / dark color tokens when configured |
Example
1curl "https://api.inference.sh/embed/agents/myteam/support-agent" \2 -H "X-API-Version: 2" \3 -H "Origin: https://example.com"Run agent
POST /embed/agents/run
Start or continue a chat with a published agent. Billing runs on the publisher's team.
Request
| Field | Type | Required | Description |
|---|---|---|---|
agent | string | Yes | Agent ref (namespace/name) |
chat_id | string | No | Existing chat ID (omit for a new chat) |
input | object | Yes | Message payload (text, optional attachments) |
stream | boolean | No | If true, response is SSE instead of JSON |
Example (JSON response):
1curl -X POST https://api.inference.sh/embed/agents/run \2 -H "Content-Type: application/json" \3 -H "X-API-Version: 2" \4 -H "Origin: https://example.com" \5 -d '{6 "agent": "myteam/support-agent",7 "input": { "text": "Hello" }8 }'Example (streaming): set "stream": true and use Accept: text/event-stream. Events match chat streaming.
Errors
| HTTP | When |
|---|---|
| 404 | Agent not published or ref not found |
| 403 | Origin not in allowed_origins |
| 402 | Publisher team has insufficient balance |
Chat and tool endpoints
After a run creates a chat, use these paths under /embed (same shapes as the authenticated Agents API, but scoped to embed access):
| Method | Path | Purpose |
|---|---|---|
GET | /chats/{id} | Chat state and messages |
GET | /chats/{id}/status | Chat status only |
POST | /chats/{id} | Send a follow-up message |
POST | /chats/{id}/stop | Stop generation |
GET | /chats/{id}/stream | SSE message stream |
POST | /tools/{toolId} | Submit client tool result |
POST | /tools/{toolId}/invoke | Approve a pending tool |
POST | /tools/{toolId}/reject | Reject a pending tool |
Embed chat access is limited to chats created in the embed session (creator-scoped). Execution and billing use the agent owner's team.
JavaScript SDK
Point the SDK at the embed base URL and omit the API key:
1import { createClient } from '@inferencesh/sdk';2import { AgentChatProvider, useAgentChat } from '@inferencesh/sdk/agent';34const embedClient = createClient({5 baseUrl: 'https://api.inference.sh/embed',6 getToken: () => '',7 credentials: 'include',8});910// Use embedClient with AgentChatProvider — same hooks as authenticated chatRegister client tool handlers for built-in embed tools when using a custom UI:
| Tool | Handler role |
|---|---|
get_host_context | Return JSON from your host page bridge |
send_to_host | Forward action / params to the parent window |
The hosted embed page implements these via postMessage. See Publishing — host page context.
Host context tools
When host_context is enabled on the agent, the model may call:
get_host_context— Read URL, user info, tokens, or other data the host supplied viaembed:contextmessages.send_to_host— Request host actions (navigate,refresh,click, custom actions). The host page responds withembed:action:result.
These execute in the browser (client tools), not on inference.sh servers.