Resumen de API

Esta es la documentación de la API pública de la nube de Capgo. La API te permite gestionar programáticamente tus recursos de Capgo, incluyendo organizaciones, dispositivos, canales y bundles. Está diseñada bajo arquitectura RESTful y utiliza métodos HTTP estándar.

Autenticación

Todos los endpoints de API requieren autenticación. Para autenticar tus peticiones, añade tu clave API en el x-api-key header, o envíala como Authorization: Bearer YOUR_API_KEY.

Ejemplo:

curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/organization/

Obtener clave API Genera tu clave API en el dashboard de Capgo

El authorization header con la clave en bruto (sin Bearer prefijo) sigue siendo aceptado para integraciones legacy, pero x-api-key es el header recomendado para todos los tipos de clave, incluidas las claves hash seguras.

Los agentes de IA y otros clientes OAuth pueden obtener una clave mediante OAuth 2.0 (autorización code con PKCE y registro dinámico de clientes). El emisor es https://capgo.app, con metadatos en https://capgo.app/.well-known/oauth-authorization-server. El usuario elige a qué organizaciones conceder acceso, y el access token es una clave Capgo API enviada como Bearer token.

Versionado

La API se versiona por fecha. Fija una versión con el capgo_api header de la petición:

curl -H "x-api-key: YOUR_API_KEY" -H "capgo_api: 2025-10-01" https://api.capgo.app/organization/

Sin el header obtendrás la versión por defecto, actualmente 2025-10-01. Los cambios dentro de una versión son aditivos: nuevos endpoints, nuevos parámetros opcionales y nuevos campos de respuesta. Un breaking change se lanza como una nueva versión con fecha, y los clientes fijados a una fecha anterior mantienen el comportamiento antiguo. Una versión desconocida o malformada devuelve 400 unsupported_capgo_api_version o 400 invalid_capgo_api_version.

Eliminar una operación o campo es un breaking change, por lo que solo ocurre en una nueva versión con fecha. Nada está deprecated actualmente. Cuando algo lo esté, la operación se marcará deprecated: true en la Especificación OpenAPI, sus respuestas incluirán un Deprecation encabezado (RFC 9745) y un Sunset encabezado (RFC 8594) con la fecha de fin del comportamiento anterior, y el cambio se anunciará en la notas de la versión.

Límites de tasa (Rate Limiting)

API implementa rate limiting para garantizar un uso justo. Los límites actuales son:

• 2,000 solicitudes por minuto por clave de API
• 20.000 solicitudes por minuto por clave API en las rutas de upload de bundles
• 20 claves inválidas de API por IP en 15 minutos; después, la IP se bloquea durante 15 minutos

Cada respuesta informa de la cuota con los RateLimit-Policy y RateLimit headers (borrador de IETF):

RateLimit-Policy: "apikey";q=2000;w=60
RateLimit: "apikey";r=1995;t=42

q es la cuota, w la ventana en segundos, r las solicitudes restantes y t los segundos hasta que se reinicie la ventana. Si superas un límite, recibirás una respuesta 429 (Too Many Requests) con un Retry-After encabezado en segundos.

Cambios de canal del dispositivo

Los cambios de canal del dispositivo usan el plugin API y tienen límites de prevención de abuso independientes para cada plan, incluyendo las pruebas:

• Un dispositivo puede realizar hasta 5 solicitudes por segundo para cada operación de canal (set, get, delete, o list). Este límite se aplica a la app, al dispositivo y a la operación.
• Configurar el mismo dispositivo en el mismo canal más de una vez en 60 segundos devuelve una respuesta 429. Cambiar a un canal distinto está permitido tras el reinicio del límite por segundo.
• Se aplica un límite adicional de 1000 solicitudes de canal por minuto a cada app y dirección IP.

Estos límites no son globales de la cuenta. Si tu switcher de canales puede volver a un canal seleccionado recientemente, espera la retryAfterSeconds duración indicada en la respuesta 429 antes de reintentar.

Formato de respuesta

Todas las respuestas están en formato JSON. Las respuestas exitosas suelen incluir un data objeto o un status campo. Las respuestas de error incluyen un error code legible por máquinas, un messagelegible por humanos, moreInfo detalles.

Ejemplo de respuesta exitosa:

{
  "status": "ok",
  "data": { ... }
}

Ejemplo de respuesta de error:

{
  "error": "invalid_apikey",
  "message": "Invalid apikey",
  "moreInfo": {}
}

Endpoints disponibles

Organizaciones Crea y gestiona organizaciones, actualiza ajustes y maneja configuraciones a nivel de organización

Claves de API Genera, lista y revoca claves API para un acceso seguro a la Capgo API

Miembros Gestiona miembros, roles y permisos de la organización

Estadísticas Accede a analíticas detalladas sobre el uso de la app, almacenamiento y consumo de ancho de banda

Canales Controla los canales de actualización, bundles (versiones) y políticas de actualización de la app

Dispositivos Rastrea y gestiona los dispositivos que ejecutan tu app, incluyendo bundles (versiones) y canales asignados

Bundles Gestiona los bundles de la app, incluyendo la subida, listado y gestión de versiones.

Buenas prácticas

1. Manejo de errores: Comprueba siempre las respuestas de error y gestiónalas adecuadamente
2. Límites de tasa (Rate Limiting)Implementa exponential backoff al alcanzar los límites de tasa (rate limits)
3. Caché: Cachea las respuestas cuando sea oportuno para reducir las llamadas a API
4. Versionado: Sigue los cambios de API en nuestro changelog

Continúa desde la descripción general de API

Si estás usando Resumen de API para planificar los flujos de autenticación y de cuenta, conéctalo con @capgo/capacitor-social-login para los detalles de implementación en @capgo/capacitor-social-login, @capgo/capacitor-passkey para el detalle de implementación en @capgo/capacitor-passkey, @capgo/capacitor-native-biometric para el detalle de implementación en @capgo/capacitor-native-biometric, Autenticación de dos factores para el detalle de implementación en la autenticación de dos factores, y SSO (Enterprise) para el detalle de implementación en SSO (Enterprise).