Conceptos básicos de la API REST
Las mismas operaciones que las herramientas MCP, como JSON sobre HTTP. Las estructuras importantes que debes conocer y dónde se encuentra la referencia completa.
La API REST es para scripts de CI y clientes sin MCP. Mismas operaciones, misma validación, misma forma de error que las herramientas.
Conceptos básicos
- URL base:
https://app.tileset.com. - Autenticación:
Authorization: Bearer <API key>en cada llamada. Consulta Claves de API. - Los cuerpos son JSON. Un valor incorrecto devuelve un error con
field,receivedyallowed, de modo que un script pueda corregirse a sí mismo. Crear un widget y cambiar uno rechazan un valor incorrecto de la misma manera.
Las llamadas que usarás
| Llamada | Hace |
|---|---|
POST /v1/sources | Conecta una fuente: type, "mode": "live", además de una de: query (Google), channelHandle (YouTube), podcast (RSS, un enlace de Apple Podcasts de un programa o dirección de feed, en lugar de feedUrl), pinterestUrl (un enlace de perfil o tablero de Pinterest), xHandle (un @handle o enlace de perfil de X), twitchChannel (un nombre de canal de Twitch o enlace de twitch.tv), kickChannel (un nombre de canal de Kick o enlace de kick.com). label es opcional: déjalo fuera y la fuente se nombra según su cuenta o negocio (una fuente de testimonios solo toma type y label). Sin "mode": "live" obtienes una fuente de demostración con contenido de ejemplo; con él, una solicitud que omite el campo de su tipo responde con un 400 nombrando el campo. |
GET /v1/sources, GET/PATCH/DELETE /v1/sources/:id | Lista, lee, cambia o elimina fuentes. PATCH toma label (renombrar), updateEvery, manualOnly y schedule. Un PATCH con varias partes las guarda todas o ninguna. |
POST /v1/sources/:id/testimonials, GET /v1/sources/:id/testimonials | Agrega hasta 20 testimonios (esperan aprobación en el panel), o cuenta los pendientes, aprobados y filtrados (solo se revisan los testimonios enviados a través del enlace, nunca lo que agrega una clave). Una clave nunca lee las entradas de vuelta. La aprobación, el rechazo (uno a la vez o varios a la vez), la edición, la eliminación, el orden y la pausa o reanudación del enlace responden a una clave de API con 403: una persona hace esas cosas en el panel. |
GET /v1/sources/:id/content | Recuentos para elegir un diseño: cuántos elementos, sus fechas y ritmo, calificaciones con estrellas, fotos y vídeos, formas de imágenes, longitudes de texto, sistemas de escritura y respuestas del propietario. Nunca los elementos. |
GET/POST /v1/bio, GET/PATCH/DELETE /v1/bio/:id | Lista o crea páginas de “Link in bio” (name, los campos de la página y slug en Starter y superior; sin uno, la página se asigna una dirección), y lee, cambia (blocks reemplaza la lista, style cambia solo las claves que envías) o elimina una. POST /v1/bio/:id/blocks añade bloques, GET /v1/bio/slug?slug=<slug> comprueba si una dirección está libre y GET /v1/bio/:id/analytics?days=7|30|90 devuelve vistas y clics de enlaces (los últimos 7 días necesitan un plan superior). Una dirección ocupada responde 409; una página que excede el recuento del plan o un campo restringido responde 403. |
POST /v1/widgets | Crea un widget a partir de una fuente (sourceId, type, más opciones), o a partir de hasta cuatro con sourceIds para un feed mixto |
GET /v1/widgets, GET/PATCH/DELETE /v1/widgets/:id | Lista, lee, modifica o elimina widgets. |
POST /v1/widgets/:id/check-page | Comprueba una página para este widget (url): la misma comprobación que la herramienta verify_install. Responde verified, lo que encontró en lines, y hints con una solución para cada error común. Se rechaza una dirección local o privada con 400; 30 comprobaciones por hora. |
GET /v1/credits, PATCH /v1/credits | Saldo y proyección; establece el límite mensual. |
GET /v1/prices | Público, sin clave: cuánto cuesta una actualización por tipo de fuente. |
GET /v1/widgets/:id/content | Público, con CORS: la lectura propia del embed, solo para visualización a través del widget (no una API de datos) |
POST /v1/hooks/:secret | Webhook de una fuente (sin clave; el secreto es la credencial) |
Una cuenta tiene como máximo 200 widgets.
Recuentos, nunca contenido
Una clave nunca lee tu contenido: ninguna llamada responde con una publicación o una reseña. Para ver el resultado, abre https://app.tileset.com/preview/<widgetId>, el widget tal como lo ven los visitantes. El error de una fuente fallida se lee como una frase fija.
Uso justo
Los límites de uso justo responden 429 con reason, why, limit y retryAt, además de una cabecera Retry-After: espera hasta entonces, no reintentes antes. Una búsqueda de nombre de negocio que excede el límite diario también responde 429. Una nueva fuente de Google que excede el número diario compartido se conecta con queued, y lista con firstFetchQueued verdadero hasta que sus reseñas lleguen después de las 00:00 UTC.
Referencia completa
La referencia completa y actual es llms.txt. Se genera a partir del mismo código fuente que las herramientas MCP, por lo que ambas siempre coinciden. Tu página nunca llama directamente a la API: solo carga el script del widget.