teddy/Docs

Documentation

Teddy publishes HTML pages (artifacts) and small APIs (functions) with an instant URL. Built for your AI agent to use, and for you too, from code.

Get started

1. Create your account with your email (magic link, no password). For scripts or clients without OAuth, also create an agent API key tdy_ under Agent keys.

2. Connect your agent. In Claude (web, desktop, mobile, Cowork or Claude Code), add a custom connector with this URL. Claude will ask you to sign in to Teddy and grant permission; no API key is needed:

http://192.168.0.10:3579/mcp

3. Publish. Ask your agent ("publish this on Teddy") or do it yourself:

curl -X POST http://192.168.0.10:3579/api/artifacts \
  -H "Authorization: Bearer $TEDDY_KEY" \
  -H "Content-Type: text/html" \
  --data-binary @pagina.html

The response includes url: share it. Each artifact is served in isolation (sandboxed iframe with CSP), with no access to your session.

Artifacts

An artifact is a self-contained HTML file (CSS and JS inline). It is published at /a/<id> with a minimal Teddy bar and a report button.

curl -X POST http://192.168.0.10:3579/api/artifacts -H "Authorization: Bearer $TEDDY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html":"<h1>Hola</h1>","title":"Saludo","folder":"Demos","expires_in":"7d"}'

Functions

A function is a JavaScript module that Teddy runs in a sandbox (V8 isolate, the same engine as Cloudflare Workers) and exposes at /f/<id>, with any method and subpath.

export default {
  async fetch(request, env) {
    const { importe = 0 } = await request.json().catch(() => ({}));
    return Response.json({ importe, iva: +(importe * 0.21).toFixed(2) });
  }
};
curl -X POST http://192.168.0.10:3579/api/functions -H "Authorization: Bearer $TEDDY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"IVA","code":"export default { async fetch(r) { return Response.json({ ok: true }) } }"}'

Access to your APIs

Each function has an access mode (access):

curl -X POST http://192.168.0.10:3579/api/functions/<id>/keys -H "Authorization: Bearer $TEDDY_KEY" \
  -H "Content-Type: application/json" -d '{"name":"Cliente Acme","rate_per_min":60,"expires_in":"30d"}'

curl http://192.168.0.10:3579/f/<id> -H "Authorization: Bearer tfk_…"   # o X-API-Key, o ?api_key=

The function never sees the key: it receives x-teddy-key-name with the key's name (encoded with encodeURIComponent) and x-teddy-key-id; any x-teddy-* header sent by the client is discarded. Calls with a tfk_ key receive X-RateLimit-Limit and X-RateLimit-Remaining. Rejected attempts (401/403/404/429) are logged with their reason, appear in the dashboard and in /rejections, and do not consume quota or rate limit.

Scheduled functions (cron)

A function can run on its own. You define a 5-field cron expression in UTC (minute hour day-of-month month day-of-week; it supports lists, ranges, steps, names such as mon-fri and the aliases @hourly, @daily, @weekly) and Teddy calls the function with a POST to the path you choose, with the body you configure. Three headers arrive that nobody outside can forge: x-teddy-cron: 1, x-teddy-schedule-id and x-teddy-scheduled-for (the planned time).

curl -X POST http://192.168.0.10:3579/api/functions/<id>/schedules \
  -H "Authorization: Bearer $TEDDY_KEY" -H "Content-Type: application/json" \
  -d '{"cron":"0 9 * * mon-fri","path":"/informe","body":{"dias":7},"name":"Informe diario"}'

It counts against the plan's daily invocations and respects the maximum time per invocation. Free: 2 schedules, at most once per hour; Pro: 50, every 5 minutes. If Teddy is down at the scheduled time, the run happens once when it comes back (not every missed one). Each run is kept in a 14-day log (GET /api/functions/<id>/schedules/<sid>/runs, or in the dashboard); after 10 consecutive failures the schedule disables itself and says so, and re-enabling it resets the counter. If the function is paused or the account suspended, the run is skipped and noted.

Secrets

For keys to external APIs. Never put them in the code: store them as a secret and read them with env.NAME.

curl -X PUT http://192.168.0.10:3579/api/functions/<id>/secrets/OPENAI_API_KEY -H "Authorization: Bearer $TEDDY_KEY" \
  -H "Content-Type: application/json" -d '{"value":"sk-…"}'
export default {
  async fetch(request, env) {
    const r = await fetch("https://api.openai.com/v1/models", { headers: { Authorization: "Bearer " + env.OPENAI_API_KEY } });
    return new Response(r.body, r);
  }
};   // con allow_net: ["api.openai.com"]

Names in UPPERCASE with digits and _ (KV, FN_* and TEDDY_* are reserved); values from 4 B to 4 KB. They are stored encrypted (AES-256-GCM). The value cannot be read back and, if it appears in a log or an error, it shows as ••••.

Memory (KV)

Each published function has its own key-value store, persistent across calls:

export default {
  async fetch(request, env) {
    const visitas = Number(await env.KV.get("visitas") ?? 0) + 1;
    await env.KV.put("visitas", String(visitas));
    await env.KV.put("ultima", JSON.stringify({ t: Date.now() }), { expirationTtl: 86400 });
    const { keys } = await env.KV.list({ prefix: "u:" });
    return Response.json({ visitas, ultima: await env.KV.get("ultima", "json"), usuarios: keys.length });
  }
};

Values are text (use JSON.stringify). From the dashboard or the API you can list, read and delete keys. run_code has no KV.

Data (collections)

A collection is a list of JSON records with its own API at http://192.168.0.10:3579/d/<id>: you store orders, form responses or an app's state without setting up a database. Reading and writing each have their own access: public (anyone, with a per-IP limit), key (a tfk_… key or a management key) or owner (only you). The pages you publish can call it directly with fetch (open CORS).

# crear un registro y leerlos con filtros
curl -X POST http://192.168.0.10:3579/d/ID -H "Content-Type: application/json" -d '{"nombre":"Ana","mesas":2}'
curl "http://192.168.0.10:3579/d/ID?mesas__gte=2&_order=-mesas&_limit=20"
# cambiar un campo (null lo borra) solo si nadie lo cambió antes
curl -X PATCH http://192.168.0.10:3579/d/ID/REGISTRO -H "If-Match: 1" -d '{"mesas":3}'

Filters: field=value, field__gt, __gte, __lt, __lte, __ne; ordering _order=-field; _limit (max. 100), _offset, _count=1. Each record has id, version and dates; If-Match: <version> prevents overwriting someone else's changes (409 version_conflict). An optional schema (a subset of JSON Schema) validates what is written.

From a function: env.DB.collection("pedidos") with find, get, insert, put, patch and delete; it only sees its owner's collections. run_code has no DB. From the dashboard (Data) you can view records, change access and export to CSV or JSON; the management API (/api/collections) also imports up to 1,000 records per call.

Real time

A channel (http://192.168.0.10:3579/c/<id>) delivers JSON messages instantly to everyone listening: chat, scoreboards, notifications, dashboards that update themselves. Publishing and listening each have their own access (public, key or owner), as with collections. Create them in the dashboard (Channels), with the API or with your agent.

// en una página publicada: escuchar (SSE; se reconecta solo y no pierde mensajes)
const es = new EventSource("http://192.168.0.10:3579/c/ID");
es.onmessage = (e) => console.log(JSON.parse(e.data));
es.addEventListener("marcador", (e) => console.log("gol", JSON.parse(e.data)));

// publicar
fetch("http://192.168.0.10:3579/c/ID?event=marcador", { method: "POST", body: JSON.stringify({ local: 2, visitante: 1 }) });

// WebSocket: lo que llega es {id, event, data}; lo que escribas (JSON) se publica
const ws = new WebSocket("wss://TU-DOMINIO/c/ID");
ws.onmessage = (e) => console.log(JSON.parse(e.data));
ws.onopen = () => ws.send(JSON.stringify({ hola: "mundo" }));

Channels with a key (tfk_…, account-wide) receive it in Authorization: Bearer or X-API-Key; browsers cannot set headers on EventSource or WebSocket, so there it goes in ?api_key=. Cookies are never used. On reconnect, Last-Event-ID (or ?after=) recovers what was missed from the channel's last 100 messages: messages are not stored on disk, so if you need history, save them to a collection.

GET /d/<id>/_events streams a collection's changes live (created, updated, deleted) with the same access rule as reading it: a page can display the data and keep it up to date without polling. From a function, await env.CHANNELS.publish("nombre", datos, "evento") notifies the listeners of your account's channel (it does not exist in run_code).

Known limitation: the message bus lives in the memory of a single Teddy process; with multiple instances a shared bus would be needed (Postgres LISTEN/NOTIFY). Heartbeats (: ping every 25 s) keep the connection alive behind proxies.

Login for your customers

Your page can ask its own visitors to sign in (with Google) without you building anything: Teddy handles the login on its own domain, the customer confirms they want to sign in, and your page and your functions know who they are. They are not Teddy accounts: they are your customers, yours alone (you see them under Customers).

<script src="http://192.168.0.10:3579/sdk/teddy.js"></script>
<script>
  await Teddy.ready;                          // recupera la sesión si ya había una
  if (!Teddy.user) await Teddy.login();       // abre el popup de Teddy
  console.log(Teddy.user.email, Teddy.user.name);
  Teddy.onChange((u) => console.log("ahora:", u));
  // Teddy.fetch añade la sesión; tu función recibe la identidad en cabeceras de confianza
  const r = await Teddy.fetch("http://192.168.0.10:3579/f/ID_FUNCION/mis-pedidos");
  await Teddy.logout();
</script>

The function (with access: "user") receives x-teddy-user-id (eu_…, stable per customer and owner), x-teddy-user-email, x-teddy-user-name (encoded with encodeURIComponent) and x-teddy-user-provider. They are trusted: Teddy discards any x-teddy-* header sent by the client and the function never sees the token. Without a valid session it responds 401 (login_required or invalid_session). Keeping each customer's data separate is up to you (e.g. an owner_email field in your records, filtering by it inside the function with env.DB): that way the page never reads other customers' data.

export default { async fetch(req, env) {
  const email = decodeURIComponent(req.headers.get("x-teddy-user-email"));
  const mine = await env.DB.query("presupuestos", { filters: { cliente: email } });
  return Response.json(mine.items.map((r) => r.data));
} }
Limits and details. Login only works on the normal page (/a/<id>), not in ?bare=1 mode (Teddy.login() fails with no_shell). The session lasts 14 days, lives in that customer's browser and can be closed or deleted from the dashboard; it stops being valid if you pause or delete the page where it started. Customers who have not signed in for 90 days and have no session are removed automatically (freeing up quota). Teddy.fetch only sends the session to this Teddy's functions (/f/…). Maximum customers per plan: Free 100, Pro 100,000. Your pages still run in an isolated environment: you cannot embed the Google button inside it (its origin is opaque); use Teddy.login(). You can embed third-party content with <iframe>, which inherits that isolation and sends no Referer: those that require it (the YouTube player) show an error; those that do not (many maps and widgets) work. Providers: Google (requires GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET on the server and registering http://192.168.0.10:3579/eu/google/callback as the redirect URI); the "test account" is for demonstration only and is never active in production.

MCP for agents

Remote MCP server (Streamable HTTP) at http://192.168.0.10:3579/mcp. Two ways to authenticate:

Every tool declares a title and whether it only reads or whether it changes/deletes things (readOnlyHint / destructiveHint). Available tools:

publish_artifactPublishes HTML and returns the URL. Accepts title, folder (by name), status and expiry.
update_artifactReplaces the HTML or changes title, folder, status (live/paused) or expiry.
delete_artifactDeletes an artifact.
get_artifactMetadata of an artifact.
list_artifactsLists your artifacts; filter by folder and status.
list_artifact_versionsVersion history of an artifact.
restore_artifact_versionRepublishes a previous version (as a new version).
create_share_linkCreates a secret link for sharing (also if private), with optional label and expiry.
list_share_linksSecret links of an artifact with their visit counts.
revoke_share_linkRevokes a secret link (it no longer opens the artifact).
list_foldersYour folders and how many artifacts each has.
list_templatesTemplates for students, developers and teams: class notes, quiz, flashcards, study plan, project guide and meeting minutes.
get_templateThe HTML of a template, to keep its structure and change only the content.
run_codeRuns code once in the sandbox, without publishing.
publish_functionPublishes a function as the endpoint /f/<id>.
update_functionNew version, name, access, network or status.
list_functionsLists your functions.
function_logsLatest invocations with status, timings, console.log and rejections.
delete_functionDeletes a function.
create_function_keyCreates a tfk_ consumption key with limits and expiry.
list_function_keysLists consumption keys and their usage.
revoke_function_keyRevokes a key instantly.
set_function_secretStores an encrypted secret (env.NAME).
list_function_secretsNames of the secrets (never values).
delete_function_secretDeletes a secret.
create_scheduleSchedules a function with a cron (UTC).
list_schedulesLists your scheduled functions and their last result.
update_scheduleChanges cron/path/body or enables and disables a schedule.
delete_scheduleDeletes a schedule.
schedule_runsRun log of a schedule.
get_usageHow much of your plan you have used (artifacts, space, functions) and how much is left.
list_domainsYour own domains and which artifact each serves (root and paths); each domain comes with automatic sitemap, robots and IndexNow.
set_domainServes a public artifact at the root of your own domain (gives you the DNS record to create; the certificate is issued automatically).
claim_subdomainPublishes your artifact at name.teddyagent.app (free: 1 subdomain, Pro: 10; first come, first served).
set_domain_routeServes another artifact at a path on your domain (e.g. /opinion).
remove_domainStops serving on your domain, or removes a path.
whoamiYour email, plan, limits and usage.
list_collectionsLists your data collections with their access and size.
create_collectionCreates a data collection with its /d/<id> API (access and optional schema).
update_collectionChanges the name, access or schema of a collection.
delete_collectionDeletes a collection and all its records.
list_channelsLists your real-time channels with their access and listeners.
create_channelCreates a real-time channel (/c/<id>) for live messages over SSE or WebSocket.
update_channelChanges the name or access of a channel (closes open connections).
delete_channelDeletes a channel and disconnects its listeners.
publish_messagePublishes a JSON message to a channel: it reaches its listeners instantly.
read_messagesReads the latest messages of a channel (in-memory ring buffer).
query_recordsReads records with filters, ordering and pagination.
write_recordCreates, replaces or merges a record (with version control).
delete_recordDeletes a record.
list_end_usersLists the customers who have signed in on your pages.
delete_end_userDeletes a customer and closes their sessions.

Your domain

An artifact always lives at https://teddyagent.app/a/<id>. You can also serve it at your own address, from the chat or the API, without touching servers:

Privacy: on your domain there is no teddy panel and no teddy cookies; only your content and an anonymous visit cookie (no third parties).

Plans and limits

FreePro
Artifacts501000
Size per artifact2 MB10 MB
Publishes per hour60600
Agent keys520
Functions10200
Code per function256 KB1 MB
Time per invocation10 s30 s
Invocations per day10.0001.000.000
Calls/min per key (default)6006000
Calls/min per IP (public APIs)120600
run_code executions per hour1201200
Secrets per function20100
KV: keys / space1000 / 10 MB100.000 / 1 GB
KV: size per value64 KB1 MB
Collections550
Records per account5000500.000
Size per record16 KB256 KB
Data: total space20 MB5 GB
Channels5100
Channel message16 KB64 KB
Messages/s per channel20200
Listeners per channel1002000
Open connections per account2005000

Exceeding a limit returns 429 (or 403 if it is a quota), with a clear message and, where applicable, Retry-After.

Upgrade to Pro: in the dashboard, Plan → "Upgrade to Pro" (monthly payment; cancel any time and keep Pro until the end of the paid month). Going back to Free deletes nothing: whatever exceeds the limits stays, but you cannot create more until you are below them. Buying or cancelling is only done from the dashboard; with a key you can check the status at GET /api/billing.

REST API

Base http://192.168.0.10:3579. Authentication Authorization: Bearer tdy_…. Full specification at /openapi.json (OpenAPI 3.1): import it into Postman or Insomnia, or generate a client.

Account

GET/api/healthService status no key
GET/api/plansPlans and limits no key
GET/api/meWho am I: email, plan, limits and usage
GET/api/billingPlan, subscription and payment history
GET/api/me/exportDownload all your data (ZIP)
GET/api/me/onboarding"Getting started" status
GET/api/usagePlan usage: artifacts, space and functions against the limits (level ok, warn at 80 %, full at 100 %)

Artifacts

GET/api/artifactsList my artifacts
POST/api/artifactsPublish an artifact
GET/api/artifacts/{id}View an artifact (metadata) no key
PUT/api/artifacts/{id}Replace the HTML
PATCH/api/artifacts/{id}Change title, status (live/paused), folder, expiry, visibility (public/private) or password
DELETE/api/artifacts/{id}Delete
GET/api/artifacts/{id}/filesThe artifact's files besides the HTML (current version)
GET/api/artifacts/{id}/versionsVersion history (every published HTML)
GET/api/artifacts/{id}/versions/{n}Content of a version (JSON with html, or ?format=html to download it)
POST/api/artifacts/{id}/versions/{n}/restoreRestore a version (published as a new version)
GET/api/artifacts/{id}/diffLine-by-line differences between two versions
POST/api/artifacts/{id}/reportReport an artifact (abuse, phishing…) no key

Folders

GET/api/foldersList folders
POST/api/foldersCreate folder
PATCH/api/folders/{id}Rename
DELETE/api/folders/{id}Delete (artifacts become "no folder")
POST/api/folders/{id}/indexCreate (or update) the "Index · folder" page with links to everything in the folder

Agent keys

GET/api/keysList my tdy_ keys
POST/api/keysCreate a tdy_ key (shown only once)
DELETE/api/keys/{id}Revoke

Functions

GET/api/functionsList my functions
POST/api/functionsPublish a function as the endpoint /f/{id}
GET/api/functions/{id}View a function (with code)
PUT/api/functions/{id}Publish a new version of the code
PATCH/api/functions/{id}Change name, status (live/paused), access, network or folder
DELETE/api/functions/{id}Delete (with its keys, secrets and memory)
GET/api/functions/{id}/logsLatest invocations (including rejected ones, with reason)

Function access

GET/api/functions/{id}/usageUsage over the last 7 days per key
GET/api/functions/{id}/rejectionsRejected attempts (7 days) by reason
GET/api/functions/{id}/keysConsumption keys valid for this function
POST/api/functions/{id}/keysCreate a tfk_ consumption key for this function only
GET/api/function-keysAll my consumption keys
POST/api/function-keysCreate a consumption key (for one function or all)
PATCH/api/function-keys/{id}Change name and limits
DELETE/api/function-keys/{id}Revoke instantly

Secrets

GET/api/functions/{id}/secretsList secret names (never values)
POST/api/functions/{id}/secretsCreate or replace a secret
PUT/api/functions/{id}/secrets/{name}Create or replace a secret by name
DELETE/api/functions/{id}/secrets/{name}Delete a secret

Schedules

GET/api/schedulesAll my scheduled functions
GET/api/functions/{id}/schedulesSchedules of this function
POST/api/functions/{id}/schedulesSchedule the function (5-field cron, in UTC)
GET/api/functions/{id}/schedules/{sid}View a schedule
PATCH/api/functions/{id}/schedules/{sid}Change cron, path, body, name, or enable/disable it
DELETE/api/functions/{id}/schedules/{sid}Delete the schedule (and its log)
GET/api/functions/{id}/schedules/{sid}/runsRun log (14 days)
POST/api/functions/{id}/schedules/{sid}/runRun it now (max. 20 per hour)

Memory (KV)

GET/api/functions/{id}/kvList the keys of the function's KV
DELETE/api/functions/{id}/kvEmpty the KV
GET/api/functions/{id}/kv/{key}Read a key
DELETE/api/functions/{id}/kv/{key}Delete a key

Execution

POST/api/runRun code once, without publishing

Data (collections)

GET/api/collectionsList your collections
POST/api/collectionsCreate a data collection
GET/api/data-usageData usage: collections, records and bytes against the plan
GET/api/collections/{id}View a collection
PATCH/api/collections/{id}Change name, access or schema
DELETE/api/collections/{id}Delete the collection and all its records
GET/api/collections/{id}/recordsRecords of the collection (owner view; same filters as the public API)
POST/api/collections/{id}/recordsCreate a record (the body is the JSON object itself)
DELETE/api/collections/{id}/recordsEmpty the collection
GET/api/collections/{id}/records/{rid}Read a record
PUT/api/collections/{id}/records/{rid}Replace (or create with that id) a record; `If-Match` header with the version
PATCH/api/collections/{id}/records/{rid}Merge fields into a record (null removes a field)
DELETE/api/collections/{id}/records/{rid}Delete a record
POST/api/collections/{id}/importImport up to 1000 records at once (all or nothing)
GET/api/collections/{id}/exportExport all records (`format`: json, ndjson or csv)

Channels (real time)

GET/api/channelsList your channels
POST/api/channelsCreate a real-time channel
GET/api/channel-usageChannel and open-connection usage against the plan
GET/api/channels/{id}View a channel
PATCH/api/channels/{id}Change name or access (closes open connections)
DELETE/api/channels/{id}Delete the channel and disconnect its listeners
POST/api/channels/{id}/publishPublish a message as owner
GET/api/channels/{id}/messagesLatest messages (in-memory ring buffer; `after` = last id seen)

Channels: public API

GET/c/{id}Listen: SSE (`Accept: text/event-stream`), WebSocket (`Upgrade: websocket`) or, without them, the latest messages as JSON no key
POST/c/{id}Publish a message (body: any JSON; `?event=name`) no key

End users

GET/api/end-usersList the customers who have signed in to your apps
DELETE/api/end-users/{id}Delete a customer and close their sessions

End users: session API

GET/eu/api/meWho the customer of this session is (`Authorization: Bearer tus_…`) no key
POST/eu/api/logoutSign the customer out no key

Data: public API

GET/d/{id}List records with filters no key
POST/d/{id}Create a record no key
GET/d/{id}/{rid}Read a record no key
PUT/d/{id}/{rid}Replace or create with a chosen id (`If-Match`: version) no key
PATCH/d/{id}/{rid}Merge fields (null removes; `If-Match`: version) no key
DELETE/d/{id}/{rid}Delete (`If-Match`: version) no key
GET/d/{id}/_eventsLive changes of the collection (SSE): `created`, `updated`, `deleted` no key

Errors

Always JSON with error (human-readable text) and sometimes code (stable, for programs): unauthorized, invalid_api_key, quota_exceeded, rate_limited, too_large, moderation_rejected, no_default_export…

{ "error": "Tu plan permite 20 secretos por función", "code": "quota_exceeded" }