Referencia de la API
Todas las operaciones del contrato, con sus parámetros, sus respuestas y un botón para probarlas con tu token.
Antes de abrir la referencia
Esta referencia se genera a partir del contrato OpenAPI: ningún endpoint existe si no está en el contrato, y el mismo documento alimenta los SDK generados. Todo cuelga del prefijo fijo /api/v1; los cambios dentro de v1 son siempre aditivos y compatibles, y una v2 nacería con un plan de migración explícito.
Casi todo cuelga de una organización, y su identificador va en la ruta. Las operaciones se autentican con un Personal Access Token como bearer, que un owner o un admin crea en Ajustes → API keys: se enseña una sola vez. Un PAT se emite dentro de una organización y solo alcanza los recursos de ésa; quien no es miembro recibe un 404, no un 403.
Toda respuesta que no sea 2xx usa el mismo envelope, y su request_id coincide con la cabecera X-Request-ID: guárdala, porque es lo que hace rastreable una petición concreta. Los errores de validación devuelven 422 con code «validation_error», y ante un 429 conviene reintentar con espera exponencial.
- ¿Cómo se autentica una llamada?
- Con un Personal Access Token de tipo bearer en la cabecera Authorization. Un owner o un admin de la organización lo crea en Ajustes → API keys; se enseña una sola vez, así que cópialo entonces y guárdalo en un gestor de secretos.
- ¿Se pueden probar las operaciones desde aquí?
- Sí: cada operación del contrato trae su botón para probarla con tu token. Esto apunta a producción y lo que crees es real, así que empieza con una organización de prueba si vas a escribir.
- ¿Cómo se versiona la API?
- Con un prefijo fijo, /api/v1. Los cambios dentro de v1 son siempre aditivos y compatibles; una v2 nacería con un plan de migración explícito.
- ¿Qué pasa si una llamada falla?
- Mira el código del envelope de error y guarda la cabecera X-Request-ID, que identifica tu petición concreta. Un 401 es un token ausente, inválido o caducado; un 404, que no existe o no eres miembro de su organización; y ante un 429, reintenta más tarde con espera exponencial.