Build on StorkAI

Overview

StorkAI turns one sentence into a live AI agent — its own persona, memory, tools, chat and website. For developers, each agent exposes a small, stable HTTP surface so you can talk to it from any app, embed it in any page, and read its public profile and data.

• Base URL — https://storkai.net. Self-hosting? Swap in your own origin everywhere below.
• Public endpoints need no credentials — the chat, agent profile and on-site datasets are open (rate-limited by IP).
• Account endpoints act on your own agents and require your StorkAI session token.
• JSON everywhere — send and receive application/json; responses are UTF-8.

Quickstart

Send your first message to an agent in under a minute.

Build one at /agents/new, then copy the ID from its URL.

curl -X POST https://storkai.net/api/agents/chat \
  -H "Content-Type: application/json" \
  -d '{
    "id": "YOUR_AGENT_ID",
    "message": "Hi! What can you help me with?",
    "history": []
  }'

{
  "reply": "Hi! I can help you plan and organise anything…",
  "cards": [],
  "captured": {},
  "vibe": "open"
}

That’s the whole loop. Keep a running history and pass it back each turn for context.

Authentication

StorkAI has two access levels.

Create a revocable API key for server-to-server access at /developers/keys, then send it as a bearer token:

curl https://storkai.net/api/agents \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Core concepts

The agent object (public projection)

GET /api/agents/public returns a public-safe view of an agent — never secrets, knowledge or flow.

{
  "id": "string",
  "name": "string",
  "emoji": "string",
  "role": "string",
  "greeting": "string",
  "starters": ["string"],
  "tagline": "string",
  "accent": "#6366F1",
  "avatarUrl": "string | null",
  "featureImages": [{ "label": "string", "url": "string" }],
  "pricing": [{ "name": "string", "price": "string", "features": ["string"] }],
  "dataModules": [ /* only modules marked on-site */ ]
}

Chat with an agent

The core endpoint — the same one the embed widget and hosted site use.

Request body

Response

Example

const res = await fetch("https://storkai.net/api/agents/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    id: agentId,
    message: "Find me a vegan caterer in Lyon",
    history,           // [{ role, text }, …]
  }),
});
const data = await res.json();
console.log(data.reply);
data.cards?.forEach((c) => console.log(c.title, c.href));

Get an agent's public profile

Fetch the public projection (see the agent object) — name, greeting, starters, accent and on-site data. Cached 60s.

curl "https://storkai.net/api/agents/public?id=YOUR_AGENT_ID"

Read on-site datasets

Lists datasets an agent has published to its site (only modules marked on-site). Add &setId=… to fetch one set's rows.

# List published datasets
curl "https://storkai.net/api/agents/data?pub=1&id=YOUR_AGENT_ID"

# One dataset's rows
curl "https://storkai.net/api/agents/data?pub=1&id=YOUR_AGENT_ID&setId=SET_ID"

{ "set": { "setId": "…", "name": "Subsidies", "columns": ["name","amount"], "rows": [ … ], "count": 128 } }

Account API

These act on your own agents and require your StorkAI session token (Authorization: Bearer <token>). Each has its own rate limit.

Embed & widget

Two ways to put an agent on the web — no build step.

Inline iframe widget

<iframe
  src="https://storkai.net/embed/YOUR_AGENT_ID"
  width="420" height="640"
  style="border:0;border-radius:16px;box-shadow:0 10px 40px rgba(0,0,0,.15)"
  allow="microphone"
  title="StorkAI agent"></iframe>

Hosted site

Every agent gets a full public site at https://storkai.net/a/YOUR_AGENT_ID — hero, chat, features and data, agent-branded. Share the link, or point a custom domain at it from the agent admin.

Extensions

Official companions that put an agent one keystroke away — both are thin clients of the public chat API.

Both live in the repo under extensions/ — load unpacked (Chrome) or run with F5 (VS Code), then set your agent ID.

Connectors

An agent can pull live data from 69+ ready APIs across 13 categories — Crypto, Finance, E-commerce, Affiliate, Cloud & Dev, Data & Search and more.

• Managed — the call runs on StorkAI's key and costs credits. Zero setup for you.
• Bring your own key — store your credential (write-only) and calls run on it, free of platform credits.
• Safe by design — the model writes a {{KEY}} placeholder; the real key is injected server-side, host-allowlisted, https-only, private IPs blocked. The model never sees the key.

Data modules

Upload a CSV or JSON and it becomes a first-class dataset your agent can present and search.

• Module types — table, KPI, chart, cards.
• In chat — the agent searches your rows and returns matches as cards (no invented data).
• On the site — modules marked on-site render on the agent's public page and are readable via the public datasets API.

Rate limits

Over the limit returns 429 with a short message. Back off and retry.

Errors

Errors are JSON: { "error": "message" } with a matching HTTP status.

Versioning & stability

The public endpoints above are the stable integration surface. We add fields without breaking you — treat responses as additive and ignore unknown keys. Breaking changes will ship under a new path.

Support

Questions, quotas or an API-key/webhook need? Reach us at hello@storkai.net, or explore the platform overview and FAQ.