Documentación

Teddy publica páginas HTML (artifacts) y pequeñas APIs (funciones) con una URL al instante. Pensado para que lo use tu agente de IA, y también tú desde código.

Empezar

1. Crea tu cuenta con tu email (enlace mágico, sin contraseña). Para scripts o clientes sin OAuth, crea además una clave de agente tdy_ en Claves de agente.

2. Conecta tu agente. En Claude (web, escritorio, móvil, Cowork o Claude Code), añade un conector personalizado con esta URL. Claude te pedirá iniciar sesión en Teddy y dar permiso; no hace falta clave:

https://teddyagent.app/mcp

3. Publica. Pídeselo a tu agente («publica esto en Teddy») o hazlo tú:

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

La respuesta trae url: compártela. Cada artifact se sirve aislado (iframe con sandbox y CSP), sin acceso a tu sesión.

Artifacts

Un artifact es un HTML autocontenido (CSS y JS dentro). Se publica en /a/<id> con una barra mínima de Teddy y el botón de reportar.

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

• Actualizar: PUT /api/artifacts/{id} con el HTML nuevo (misma URL).
• Pausar / publicar: PATCH con {"status":"paused"} o "live". Pausado responde «no disponible».
• Carpetas: folder por nombre (se crea) o folder_id. Lista con GET /api/artifacts?folder=<id>|none&status=live|paused|hidden.
• Caducidad: expires_in con unidad m (minutos), h, d o w: 30m, 12h, 7d, 2w; never la quita. Al caducar se borra. (Ojo: en las claves de consumo, m son meses y también vale y.)
• Varios archivos: además del HTML, files con CSS, JS, imágenes, fuentes u otras páginas, enlazados con rutas relativas (<img src="img/logo.png">): {"html":"…","files":[{"path":"css/estilo.css","content":"…"},{"path":"img/logo.png","content":"<base64>","encoding":"base64"}]}. O sube un .zip con index.html: curl -X POST …/api/artifacts -H "Content-Type: application/zip" --data-binary @web.zip (también desde Publicar en el panel). En PUT, files sustituye todos los archivos; si solo mandas html, se conservan. Cuenta para el tamaño máximo del plan y el filtro de seguridad revisa también las otras páginas y scripts. Lista: GET /api/artifacts/{id}/files.
• Privado: "visibility":"private" (al publicar o con PATCH): solo tú lo ves; para los demás la URL responde «no existe». Para compartirlo, crea enlaces secretos con POST /api/artifacts/{id}/links ({"label":"Cliente Acme","expires_in":"7d"}): uno por persona, con contador de visitas, revocables con DELETE …/links/{linkId}. La URL del enlace solo se muestra al crearlo.
• Contraseña: "password":"…" (6–200 caracteres; null la quita). Se pide a cualquiera que lo abra, salvo a ti. Se puede combinar con privado. Todo esto también desde el panel: Biblioteca → compartir. Al pasar de público a privado, navegadores y cachés pueden seguir mostrando la versión pública hasta 60 s; quien ya lo tenga abierto con un enlace revocado puede seguir viéndolo unos minutos.
• Moderación: un filtro anti-phishing revisa cada publicación: lo evidente se rechaza (422) y lo dudoso queda oculto hasta que un admin lo revise. Tres reportes de visitantes distintos lo ocultan también.

Funciones

Una función es un módulo JavaScript que Teddy ejecuta en un sandbox (isolate V8, el mismo motor que Cloudflare Workers) y expone en /f/<id>, con cualquier método y subruta.

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 https://teddyagent.app/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 }) } }"}'

• Probar sin publicar: POST /api/run con code e input (método, ruta, query, cabeceras, body).
• Sin red por defecto. Declara los dominios con allow_net: ["api.ejemplo.com"]; solo IPs públicas.
• Solo APIs web estándar: fetch, crypto.subtle, URL, TextEncoder, streams. Sin npm ni disco.
• Tiempo: cada invocación tiene un límite (10 s en Free). Agotarlo varias veces suspende la función hasta que publiques una versión nueva.
• CORS abierto: un artifact puede llamar a tu función. Las respuestas se sirven en un origen aislado (CSP sandbox) y no pueden poner cookies.
• Logs: console.log se guarda con cada invocación (GET /api/functions/{id}/logs).

Acceso a tus APIs

Cada función tiene un modo de acceso (access):

• public: cualquiera con la URL, con límite por IP.
• key: exige una clave de consumo tfk_… que tú emites, para una función o para todas, con límite por minuto, cuota diaria y caducidad opcionales. Se revoca al instante.
• owner: solo tu clave de agente tdy_….
• user: solo clientes que han iniciado sesión en tu página (ver Login de tus clientes).

curl -X POST https://teddyagent.app/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 https://teddyagent.app/f/<id> -H "Authorization: Bearer tfk_…"   # o X-API-Key, o ?api_key=

La función nunca ve la clave: recibe x-teddy-key-name con su nombre (codificado con encodeURIComponent) y x-teddy-key-id; cualquier cabecera x-teddy-* que mande el cliente se descarta. Las llamadas con clave tfk_ reciben X-RateLimit-Limit y X-RateLimit-Remaining. Los intentos rechazados (401/403/404/429) se registran con su motivo, se ven en el panel y en /rejections, y no gastan cuota ni límite.

Funciones programadas (cron)

Una función puede ejecutarse sola. Defines una expresión cron de 5 campos en UTC (minuto hora día-del-mes mes día-de-la-semana; admite listas, rangos, pasos, nombres como mon-fri y alias @hourly, @daily, @weekly) y Teddy llama a la función con un POST a la ruta que elijas, con el cuerpo que configures. Llegan tres cabeceras que nadie de fuera puede falsificar: x-teddy-cron: 1, x-teddy-schedule-id y x-teddy-scheduled-for (la hora prevista).

curl -X POST https://teddyagent.app/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"}'

Cuenta contra las invocaciones diarias del plan y respeta el tiempo máximo por invocación. Free: 2 programaciones, como mucho una por hora; Pro: 50, cada 5 minutos. Si Teddy está parado en el momento previsto, la ejecución se hace una vez al volver (no todas las perdidas). Cada ejecución queda en un registro de 14 días (GET /api/functions/<id>/schedules/<sid>/runs, o en el panel); tras 10 fallos seguidos la programación se desactiva sola y lo dice, y al reactivarla se pone a cero. Si la función está pausada o la cuenta suspendida, la ejecución se omite y se anota.

Secretos

Para claves de APIs externas. Nunca las pongas en el código: guárdalas como secreto y léelas con env.NOMBRE.

curl -X PUT https://teddyagent.app/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"]

Nombres en MAYÚSCULAS con números y _ (KV, FN_* y TEDDY_* están reservados); valores de 4 B a 4 KB. Se guardan cifrados (AES-256-GCM). El valor no se puede volver a leer y, si aparece en un log o en un error, sale como ••••.

Memoria (KV)

Cada función publicada tiene su propio almacén clave-valor, persistente entre llamadas:

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 });
  }
};

Los valores son texto (usa JSON.stringify). Desde el panel o la API ves, lees y borras claves. run_code no tiene KV.

Datos (colecciones)

Una colección es una lista de registros JSON con su propia API en https://teddyagent.app/d/<id>: guardas pedidos, respuestas de un formulario o el estado de una app sin montar una base de datos. La lectura y la escritura tienen cada una su acceso: public (cualquiera, con límite por IP), key (clave tfk_… o de gestión) u owner (solo tú). Las páginas que publicas pueden llamarla con fetch directamente (CORS abierto).

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

Filtros: campo=valor, campo__gt, __gte, __lt, __lte, __ne; orden _order=-campo; _limit (máx. 100), _offset, _count=1. Cada registro tiene id, version y fechas; If-Match: <versión> evita pisar cambios ajenos (409 version_conflict). Un esquema opcional (subconjunto de JSON Schema) valida lo que se escribe.

Desde una función: env.DB.collection("pedidos") con find, get, insert, put, patch y delete; solo ve las colecciones de su dueño. run_code no tiene DB. Desde el panel (Datos) ves los registros, cambias accesos y exportas a CSV o JSON; la API de gestión (/api/collections) también importa hasta 1 000 registros por llamada.

Tiempo real

Un canal (https://teddyagent.app/c/<id>) reparte mensajes JSON al instante a todo el que lo escucha: chat, marcadores, avisos, paneles que se actualizan solos. Publicar y escuchar tienen cada uno su acceso (public, key u owner), como en las colecciones. Se crean en el panel (Canales), con la API o con tu agente.

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

// publicar
fetch("https://teddyagent.app/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" }));

Los canales con clave (tfk_…, de toda la cuenta) la reciben en Authorization: Bearer o X-API-Key; los navegadores no pueden poner cabeceras en EventSource ni WebSocket, así que ahí va en ?api_key=. Nunca se usan cookies. Al reconectar, Last-Event-ID (o ?after=) recupera lo perdido entre los últimos 100 mensajes del canal: los mensajes no se guardan en disco, si necesitas histórico guárdalos en una colección.

GET /d/<id>/_events emite en directo los cambios de una colección (created, updated, deleted) con la misma regla de acceso que su lectura: una página puede mostrar los datos y mantenerlos al día sin consultar. Desde una función, await env.CHANNELS.publish("nombre", datos, "evento") avisa a los oyentes del canal de tu cuenta (no existe en run_code).

Límite conocido: el bus de mensajes vive en la memoria de un único proceso de Teddy; con varias instancias haría falta un bus compartido (Postgres LISTEN/NOTIFY). Los latidos (: ping cada 25 s) mantienen viva la conexión tras proxies.

Login de tus clientes

Tu página puede pedir a sus propios visitantes que inicien sesión (con Google) sin que montes nada: Teddy hace el login en su dominio, el cliente confirma que quiere entrar, y tu página y tus funciones saben quién es. No son cuentas de Teddy: son tus clientes, solo tuyos (los ves en Clientes).

<script src="https://teddyagent.app/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("https://teddyagent.app/f/ID_FUNCION/mis-pedidos");
  await Teddy.logout();
</script>

La función (con access: "user") recibe x-teddy-user-id (eu_…, estable por cliente y dueño), x-teddy-user-email, x-teddy-user-name (codificados con encodeURIComponent) y x-teddy-user-provider. Son de confianza: Teddy descarta cualquier cabecera x-teddy-* que mande el cliente y la función nunca ve el token. Sin sesión válida responde 401 (login_required o invalid_session). Guardar los datos de cada cliente por separado (p. ej. un campo owner_email en tus registros y filtrar por él dentro de la función con env.DB) lo haces tú: así la página nunca lee datos de otros.

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));
} }

MCP para agentes

Servidor MCP remoto (Streamable HTTP) en https://teddyagent.app/mcp. Dos formas de autenticarse:

• OAuth 2.1 (lo que usa Claude): el cliente recibe un 401 con resource_metadata, lee /.well-known/oauth-protected-resource y /.well-known/oauth-authorization-server, se registra solo (registro dinámico), y tú das permiso en Teddy. PKCE S256 obligatorio; tokens de 1 h con refresh rotatorio. Retiras el acceso en Ajustes → Apps conectadas.
• Clave de agente: Authorization: Bearer tdy_…, para scripts y clientes MCP sin OAuth.

Todas las herramientas declaran título y si solo leen o si cambian/borran cosas (readOnlyHint / destructiveHint). Herramientas disponibles:

Planes y límites

Superar un límite devuelve 429 (o 403 si es de cupo), con un mensaje claro y, cuando aplica, Retry-After.

Pasar a Pro: en el panel, Plan → «Pasar a Pro» (pago mensual; cancelas cuando quieras y mantienes Pro hasta el final del mes pagado). Al volver a Free no se borra nada: lo que supere los límites sigue ahí, pero no podrás crear más hasta estar por debajo. Comprar o cancelar solo se hace desde el panel; con una clave puedes consultar el estado en GET /api/billing.

API REST

Base https://teddyagent.app. Autenticación Authorization: Bearer tdy_…. Especificación completa en /openapi.json (OpenAPI 3.1): impórtala en Postman, Insomnia o genera un cliente.

Cuenta

Artifacts

Carpetas

Claves de agente

Funciones

Acceso a funciones

Secretos

Programaciones

Memoria (KV)

Ejecución

Datos (colecciones)

Canales (tiempo real)

Canales: API pública

Usuarios finales

Usuarios finales: API de sesión

Datos: API pública

Errores

Siempre JSON con error (texto legible) y a veces code (estable, para programas): 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" }