Embed and Public Agent API

Which door do I need?

What you can do without a key

The embed needs no key, no token and no account. The element reads public facts only, and its voice is admitted by the website it runs on (the Origin your browser sends), not by a secret in the page.

A door with a switch is off until your administrator turns it on.

Put a live agent on your site: the two lines

<script src="https://app.netshow.ai/alive-kit/alive-kit.js" defer></script>
<alive-agent agent="your-agent-slug" look="auto" mode="free"></alive-agent>

That is the whole embed (the Alive Kit toolbox, docs/alive-kit/TOOLBOX.md section 1, is its owner's manual). Paste the script once, anywhere in the page, and the element where the agent should live. With agent="netshow" you get the house host.

What a visitor sees: the agent is alive as the page loads. It shows its greeting as a caption, blinks and breathes, and morphs with its room: a live ASCII face when it is tiny, the whole character when there is space. Its face is the talk button. Where your site is allowed for voice (next section), it speaks in the NetShow voice at the visitor's first touch of the page; anywhere else it stays a living, captioned look. It never uses a browser voice or a recorded clip, and it always says it is an AI.

The element

These are the attributes public/alive-kit/alive-kit.js reads. Leave out any you do not need.

Size it with CSS: --alive-agent-size (in container mode, default 320px) and --alive-agent-free-size (in free mode, default 120px). In free and stage mode the agent draws no buttons around itself: hovering it (or tapping it on a phone) shows its one menu.

The agent's public document

Class: AliveKitAgentController (methods show and package). The element fetches this for any slug other than the house host. Public agents only; the document carries public facts only, never the agent's instructions, knowledge, owner or visitors. It answers with Access-Control-Allow-Origin: * so it works from any site, and is cached for 60 seconds. 240 requests a minute.

curl --max-time 30 https://app.netshow.ai/alive-kit/v1/agents/your-agent-slug -H 'Accept: application/json'

A private agent, an unknown slug, or the switch ai.features.alive_kit_agent off: 404. The package.alive.json door answers the same file as a download (Content-Disposition: attachment).

Stores and site builders

Give it a voice on your site

The element's voice comes only from the signed mint, and the mint answers only a website the agent's owner has allowed and switched voice on for. Nothing in the page is a secret.

1. The owner allows your website. On the embed page the owner adds the origin (https://your-site.example): POST /dashboard/agents/{agentId}/embed/origins with the field origin. Class: AgentEmbedOriginController (method store). The site starts as pending. Switches: ai.features.embed_selfserve and ai.features.embed_origin_selfserve.
2. You prove you control the site. Publish the exact token the embed page shows at https://your-site.example/.well-known/netshow-origin.txt (class EmbedOriginVerification), with no redirect. Where ai.features.embed_origin_verify_meta is on, a <meta name="netshow-origin" content="..."> tag inside your home page's <head> also counts.
3. The owner presses Verify. POST /dashboard/agents/{agentId}/embed/origins/verify fetches the proof once and moves the site to active. POST /dashboard/agents/{agentId}/embed/origins/withdraw takes it off the list again (it is kept as withdrawn, never deleted).
4. The owner turns voice on for that site. POST /dashboard/agents/{agentId}/embed/origins/voice (class AgentEmbedOriginVoiceController). Switches: ai.features.widget_voice_door and ai.features.widget_voice_owner_switch.
5. Put mint-url on the element. The owner's snippet already carries it.

GET /api/widget/voice/mint-url/{slug}

Class: WidgetVoiceMintUrlController (method show). The element calls it from the visitor's browser at the visitor's first touch; the Origin header is the website asking. 10 requests a minute. Every answer carries Access-Control-Allow-Origin set to that origin and Cache-Control: private, no-store.

curl --max-time 30 https://app.netshow.ai/api/widget/voice/mint-url/your-agent-slug \
  -H 'Origin: https://your-site.example' -H 'Accept: application/json'

Response 200 (the address lives 60 seconds):

{"mintUrl": "https://app.netshow.ai/api/realtime/session/public?agent_id=...&widget_voice=embed&widget_origin=https%3A%2F%2Fyour-site.example&expires=...&signature=..."}

Where the agent has a voice ladder, the answer also carries voiceLadder, rung and voicePageUrl, the agent's own voice page.

POST /api/realtime/session/public

Class: RealtimeSessionController (method createPublic). The element posts to the signed mintUrl it was handed; the signature, the website and the agent are checked again, and the house daily ceilings apply. 10 requests a minute. The answer starts the session on the NetShow proxy voice (gpt-realtime-2.1-mini by default). You never build this request yourself: changing any query parameter breaks the signature and the door answers 403.

The owner's embed page

Class: AgentEmbedController (method show), at GET /dashboard/agents/{agentId}/embed, signed in, the agent's owner only (anyone else gets 404). Switch: ai.features.embed_selfserve. The page is titled "Put on your own website" and carries:

• The snippet. While ai.features.owner_embed_alive_kit is on, it is the two lines above for this agent, built by AliveEmbedKit::kitSnippet: look="auto", the mode that follows the agent's Own the stage setting, and its mint-url. While it is off, the page shows the older snippet for owners who already pasted it.
• Your websites. The allowed list from the section above, with each site's state and its voice switch.
• Checks. POST /dashboard/agents/{agentId}/embed/check (class AgentSnippetCheckerController, switch ai.features.studio_snippet_checker) checks a pasted snippet; POST /dashboard/agents/{agentId}/embed/live-check (class AgentEmbedLiveCheckController, switch ai.features.embed_site_live_check) loads your page once and reports whether the agent is on it.
• The WordPress plugin download (above).

Publish the agent

The embed, the public document and the public page work only for a public agent. POST /dashboard/agents/{agentId}/publish (class AgentPublishController), signed in as the owner, with a CSRF token: the field make_public (default true) sets the agent public or private. Making it public also needs confirm_publish=1; without it the agent is not changed and the page asks the owner to confirm first. Another owner's agent answers 404.

Public agent pages

POST /agent/{slug}/chat is the page's own conversation, not an API for other sites: it is a same-site browser request that needs the page's session and CSRF token. Body message (required, at most 500 characters); 5 requests a minute per visitor; 15 messages a visitor session before the page asks the visitor to sign up. Its answer:

{"reply": "<the agent's answer>", "messagesLeft": 14, "limitReached": false, "tier": "...", "greetTier": "...", "degraded": false}

and, at the cap:

{"reply": null, "limitReached": true, "signupUrl": "/register?agent=your-agent-slug"}

To talk to a public agent from your own software, use its MCP door (POST /api/agent/{slug}/mcp) or A2A door (POST /api/agent/{slug}/a2a): the MCP Integration and A2A Protocol guides show each with a request and a response.

Older embed doors

These still answer for pages that were pasted before the kit. They are not the embed to build on: a new page uses the two lines above.

How to get a key

The embed needs none. What stands in for a key is the allowed list: the agent's owner adds your website, you publish the proof file, the owner presses Verify and turns voice on. For machine access to an agent (MCP, A2A or the owner's API), see the Authentication and Keys guide.