Embed API

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: setup in the web app, origins, themes, and iframe snippets
→ Publications API — create and manage publications (POST /publications, etc.)


Base URL

code
1https://api.inference.sh/embed

No Authorization header is required. Visitors are guests identified by a cookie; see Guest session cookie.


The API signs embed visitors in as guest users and keeps their session in its own HttpOnly cookie on the API host, separate from the sign-in session cookie.

CookieProduction nameUsed for
Sign-in sessioninfsh_sessionBrowser sign-in (magic link, SSO)
Guest sessioninfsh_anonymous_sessionEmbed visitors and other anonymous routes

Outside production both names carry the environment as a suffix (infsh_anonymous_session_<env>).

On a first request without a guest cookie, the API creates a guest user and session and sets the cookie. A request that sends the cookie resumes the same guest, so the visitor keeps the chats it created in that browser. Custom UIs must send cookies on cross-origin calls (credentials: 'include' in fetch, as in the JavaScript SDK example). Origin validation still applies. Clearing the cookie or switching browsers starts a new guest. A sign-in token is never read from the guest cookie, and a guest session is never read from the sign-in cookie.


Origin validation

Published agents validate the request Origin header against the publication's allowed_origins:

allowed_originsBehavior
EmptyAll origins allowed
List of URLsOrigin must match an entry exactly, or the list may include *
Mismatch403 forbidden — origin not allowed

Configure origins in the web app's 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

FieldDescription
nameAgent display name
namespace, nameAgent ref components
versionActive version (description, example prompts, etc.)
themeOptional light / dark color tokens when configured

Example

bash
1curl "https://api.inference.sh/embed/agents/myteam/support-agent" \2  -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 workspace. New chats get origin: embed.

Request

FieldTypeRequiredDescription
agentstringYesAgent ref (namespace/name)
chat_idstringNoExisting chat ID (omit for a new chat)
inputobjectYesThe message, same MessageInput as Run agent (text, optional attachments)
streambooleanNoIf true, response is SSE instead of JSON

Example (JSON response):

bash
1curl -X POST https://api.inference.sh/embed/agents/run \2  -H "Content-Type: application/json" \3  -H "Origin: https://example.com" \4  -d '{5    "agent": "myteam/support-agent",6    "input": { "text": "Hello" }7  }'

Example (streaming): set "stream": true and use Accept: text/event-stream. Events match chat streaming.

Errors

HTTPWhen
404Agent not published or ref not found
403Origin not in allowed_origins
402Publisher workspace 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):

MethodPathPurpose
GET/chats/{id}Chat metadata (status, output, context, channel_context)
GET/chats/{id}/statusChat status only
POST/chats/{id}Send a follow-up message
POST/chats/{id}/stopStop generation
GET/chats/{id}/streamSSE message stream
POST/tools/{toolId}Submit client tool result
POST/tools/{toolId}/invokeApprove a pending tool
POST/tools/{toolId}/rejectReject 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 workspace.


JavaScript SDK

Point the SDK at the embed base URL and omit the API key:

typescript
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 chat11// For template agents with declared context fields, pass context on agentConfig:12// agentConfig={{ agent: 'my-team/pricing-agent@latest', context: { version_id: 'v1' } }}

Host context tools (deprecated)

get_host_context and send_to_host are disabled. internal_tools.host_context is ignored and agents are not offered either tool. A replacement for passing host page context to embedded agents is planned. See Internal tools.


we use cookies

we use cookies to ensure you get the best experience on our website. for more information on how we use cookies, please see our cookie policy.

by clicking "accept", you agree to our use of cookies.
learn more.