API REST

Autenticación

La API REST da a scripts y paneles los mismos datos que la aplicación. Un script llega a ella con una clave de API del espacio de trabajo enviada como bearer token. Esta página cubre las claves, sus niveles de acceso y los errores que puedes recibir.

Dirección base y formato

https://teddit.io/api

Las peticiones y respuestas son JSON. Envía Content-Type: application/json con cada cuerpo. El cuerpo de una petición puede tener hasta 4 MB.
Los ids son números. La API llama organización a un espacio de trabajo (/orgs/:orgId) y project a un sitio (/projects/:id).
Las horas son ISO 8601 en UTC. Las semanas y demás periodos se dan como una fecha, YYYY-MM-DD.

La lista de direcciones está en la página Endpoints.

Claves de API

Crea una clave en la aplicación: icono de engranaje → API y MCP → Crear clave. Cualquier rol puede; la clave recibe como máximo el acceso del tuyo.

Una clave tiene la forma tdt_ seguido de 40 letras, dígitos, - y _.
Se muestra una sola vez, al crearla. Teddit guarda un hash de ella, no la clave, así que una clave perdida no se puede recuperar. Crea una nueva en su lugar.
Una clave pertenece a un solo espacio de trabajo y puede llegar a todos sus sitios.
La lista de claves muestra el nombre de cada clave, sus primeros caracteres, su acceso, quién la creó y cuándo se usó por última vez. “Último uso” se actualiza como mucho una vez cada cinco minutos.
Una clave no caduca. Revócala con el icono de papelera; deja de funcionar con la siguiente petición.

Las mismas claves abren el servidor MCP.

Enviar la clave

Pon la clave en la cabecera Authorization de cada petición:

curl https://teddit.io/api/whoami \
  -H "Authorization: Bearer tdt_…"

GET /api/whoami es la llamada por la que empezar. Dice a qué espacio de trabajo pertenece la clave y qué puede hacer:

{
  "kind": "token",
  "tokenName": "Reporting script",
  "user": { "id": 7, "name": "Dana Whitfield", "email": "dana@brightloop.example" },
  "org": { "id": 3, "name": "Brightloop", "plan": "free" },
  "role": "viewer"
}

Usa org.id en las direcciones /orgs/:orgId/…. user es la persona que creó la clave: las acciones realizadas con la clave, como iniciar un análisis, se registran a su nombre.

La clave es toda la credencial. Mantenla fuera de páginas web, repositorios y mensajes de chat, y da a cada script su propia clave para poder revocar una sin detener las demás.

Niveles de acceso de las claves

Una clave tiene uno de tres niveles de acceso. Cada uno es un rol del espacio de trabajo, y cada uno incluye el anterior.

Acceso en la aplicación	`role`	Puede llamar
Lectura	`viewer`	Todo lo que lee: informes, prompts, respuestas, competidores, páginas, análisis, miembros. También la estimación del coste de un análisis.
Lectura + edición	`member`	Además: crear, cambiar y eliminar prompts, categorías y competidores; importar; cambiar los nombres, el idioma y el país de un sitio.
Lectura + análisis	`admin`	Además: iniciar y cancelar análisis, activar y desactivar el calendario, cambiar el tope mensual y los ajustes de análisis, añadir sitios, invitar y quitar miembros.

No hay claves con el rol Owner. Recargar, eliminar un sitio y renombrar un espacio de trabajo quedan para un Owner con sesión iniciada.
No puedes crear una clave con más acceso del que te da tu propio rol.
Una clave sigue a la persona que la creó: baja con su rol, y se detiene cuando esa persona deja el espacio de trabajo.

Qué no puede hacer una clave

Algunas acciones necesitan a una persona con sesión iniciada en la aplicación, en un navegador. Llamadas con una clave, responden 403 con “This action needs a signed-in person, not an API token.”

Crear, listar y revocar claves de API.
Cambiar tu nombre, correo o contraseña, y eliminar tu cuenta.
Crear un espacio de trabajo, eliminarlo, cambiar entre espacios de trabajo y abandonar uno.
Aceptar una invitación.

Una clave tampoco ve nada fuera de su espacio de trabajo. Un id de sitio o de espacio de trabajo que pertenece a otro responde 404, igual que un id que no existe.

Errores

Todos los errores tienen el mismo cuerpo: un mensaje para una persona en error, y fields con un mensaje por campo cuando el problema está en la entrada, si no null.

HTTP/1.1 409 Conflict

{
  "error": "This prompt already exists in the project.",
  "fields": { "text": "Already tracked" }
}

Estado	Cuándo
400	La petición está bien formada pero se rechaza: se alcanzó un límite del espacio de trabajo, un análisis no puede empezar (hay otro en curso, no hay prompts activos, el saldo no lo cubre, el tope mensual está gastado), o una dirección no es un dominio. El mensaje dice cuál.
401	Sin clave, una clave con la forma incorrecta, o una clave revocada. El mensaje es “Sign in to continue.”
403	El nivel de acceso de la clave es demasiado bajo para la acción, o la acción necesita a una persona con sesión iniciada.
404	La dirección o el id no existe, o pertenece a otro espacio de trabajo.
409	Un duplicado: un prompt con el mismo texto, un competidor o una categoría con el mismo nombre, una invitación a alguien que ya es miembro.
422	El cuerpo o la cadena de consulta no pasaron la validación. `fields` nombra cada campo incorrecto.
429	Demasiadas peticiones a una dirección con su propio límite, como el inicio de sesión, las invitaciones o la lectura del sitemap. Espera y vuelve a intentarlo.
500, 502	Algo falló por nuestra parte, o un asistente falló mientras se atendía la petición.

Las llamadas correctas responden 200 con JSON. Eliminar un sitio, un miembro o una invitación responde 204 sin cuerpo.

Límites de frecuencia y del espacio de trabajo

La mayoría de las peticiones hechas con una clave no tienen límite de frecuencia. Unas pocas acciones tienen el suyo: invitar personas, volver a leer el sitemap y reescribir consultas. Superarlo responde 429.
Los límites del espacio de trabajo se aplican a la API exactamente igual que en la aplicación: sitios, prompts por sitio, análisis al mes y miembros. Una llamada que superaría un límite responde 400 con el límite en el mensaje.
Las direcciones de lista están paginadas. La lista de prompts toma page y perPage (de 5 a 200); pedir más responde 422.

Anterior‹ Preguntas de ejemplo SiguienteEndpoints ›