La API de Tutiplay

API keys y permisos

Cómo se autentica una llamada, qué permite cada nivel de permiso, qué límites de uso se aplican y qué tener en cuenta al usar una key desde un agente.

Autenticación

Cada llamada lleva la API key en la cabecera Authorization: Bearer. No hay sesiones ni tokens que renovar: la misma cabecera sirve para todas las llamadas.

bash

curl -s \
  -H "Authorization: Bearer $TUTIPLAY_API_KEY" \
  https://api.tutiplay.com/v1/me

javascript

const res = await fetch("https://api.tutiplay.com/v1/communities", {
  headers: { Authorization: `Bearer ${process.env.TUTIPLAY_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).message);
const communities = await res.json();

python

import os, requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['TUTIPLAY_API_KEY']}"

communities = session.get("https://api.tutiplay.com/v1/communities").json()

Permisos

Al crear una key se elige uno de tres niveles. Son acumulativos: cada uno incluye lo que permite el anterior.

Nivel	Qué permite	Ejemplos
`READ`	Consultar todo lo que tu cuenta puede ver.	`GET /v1/communities` `GET /v1/communities/{slug}/rounds`
`WRITE`	Además, crear, editar y borrar tus plantillas. No permite guardar ni confirmar pronósticos.	`POST /v1/templates/1x2` `PUT /v1/templates/quiniela/{id}`
`PLAY`	Además, guardar, confirmar y deshacer pronósticos, quitar una jugada, rellenarlos con una plantilla y activar o desactivar el juego automático de una peña.	`PUT …/rounds/{round}/forecast/{n}` `PUT …/auto-play`

La regla es predecible: toda llamada GET requiere READ; las escrituras bajo /forecast y /auto-play requieren PLAY, y el resto de escrituras, WRITE. Una llamada que requiere un nivel superior al de la key responde 403 con {"error":"SCOPE"}.

Una key con PLAY consume saldo de tu cuenta: confirmar un pronóstico cobra sus columnas. Si lo que construyes solo consulta —un panel, un recordatorio, un resumen—, usa una key con READ.

Límites de uso

Los límites se aplican solo a la API de datos de fútbol: todo lo que cuelga de /v1/football/competitions, que son las competiciones, sus temporadas, sus jornadas y su clasificación. Es el grupo Datos de fútbol de la referencia. La quiniela no tiene límite: tus peñas, las jornadas con el signo de cada partido, el escrutinio, lo que se juega en toda España, tus pronósticos y tus plantillas.

Para los datos de fútbol hay un límite de llamadas por minuto y otro por día. Si se excede cualquiera de los dos, la respuesta es 429 con la cabecera Retry-After, que indica en segundos cuándo se puede volver a llamar. Los valores vigentes aparecen en la pantalla de API Keys.

bash

HTTP/1.1 429
Retry-After: 37

{"error":"TOO_FAST","message":"Too many football data calls in one minute for this account"}

El límite se mide por minuto, no por segundo, de modo que una ráfaga breve de llamadas al arrancar un cliente no se rechaza.
Se aplica a la cuenta, no a cada key: todas las keys de una cuenta comparten el mismo cupo, y crear una nueva o revocar otra no lo amplía ni lo reinicia. El número de keys activas por cuenta también está limitado.
Una llamada rechazada no consume cupo, así que un reintento que respeta la espera acaba siendo aceptado.

Se recomienda respetar Retry-After en lugar de reintentar de inmediato, y guardar en caché los datos que cambian poco, como las competiciones y sus equipos.

Agentes y MCP

La API está preparada para que la utilice un modelo de lenguaje: las rutas son estables y los errores se identifican por un código. Para usarla desde un asistente como Claude o Cursor sin escribir código, hay un servidor MCP con la misma API key: ver MCP.

En ese caso, el nivel de permiso de la key es el único límite efectivo entre lo que el agente puede consultar y lo que puede hacer con tu saldo. Esa decisión se toma al crear la key, no durante la conversación.

Empieza con una key de READ y súbela a PLAY solo cuando hayas comprobado que el agente hace lo esperado. Usa una key distinta para cada agente, para poder revocar una sin afectar al resto.