API Overview

This is the documentation of the public API of Capgo cloud. The API allows you to programmatically manage your Capgo resources, including organizations, devices, channels, and bundles. It’s designed to be RESTful and uses standard HTTP methods.

Authentication

All API endpoints require authentication. To authenticate your requests, add your API key in the x-api-key header.

Example:

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

Get API key Generate your API key in the Capgo dashboard

The authorization header is still accepted for legacy API keys, but x-api-key is the recommended header for all key types, including secure hashed keys.

Rate Limiting

The API implements rate limiting to ensure fair usage. Current limits are:

• 100 requests per minute for standard accounts
• 1000 requests per minute for enterprise accounts

If you exceed these limits, you’ll receive a 429 (Too Many Requests) response.

Device channel changes

Device channel changes use the plugin API and have separate abuse-prevention limits that apply to every plan, including trials:

• A device can make up to 5 requests per second for each channel operation (set, get, delete, or list). This limit is scoped to the app, device, and operation.
• Setting the same device to the same channel more than once within 60 seconds returns a 429 response. Switching to a different channel is allowed after the per-second limit resets.
• An additional limit of 1000 channel requests per minute applies to each app and IP address.

These limits are not account-wide. If your channel switcher can return to a recently selected channel, wait for the retryAfterSeconds duration in the 429 response before retrying.

Response Format

All responses are in JSON format. Successful responses typically include either a data object or a status field. Error responses include an error field with a description of what went wrong.

Example success response:

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

Example error response:

{
  "error": "Invalid API key",
  "status": "KO"
}

Available Endpoints

Organizations Create and manage organizations, update settings, and handle organization-level configurations

API Keys Generate, list, and revoke API keys for secure access to the Capgo API

Members Manage organization members, roles, and permissions

Statistics Access detailed analytics about app usage, storage, and bandwidth consumption

Channels Control app update channels, bundles (versions), and update policies

Devices Track and manage devices running your app, including bundle (version) and channel assignments

Bundles Handle app bundles, including uploading, listing, and managing bundles (versions)

Best Practices

1. Error Handling: Always check for error responses and handle them appropriately
2. Rate Limiting: Implement exponential backoff when hitting rate limits
3. Caching: Cache responses when appropriate to reduce API calls
4. Versioning: Keep track of API changes through our changelog

Keep going from API Overview

If you are using API Overview to plan authentication and account flows, connect it with @capgo/capacitor-social-login for the implementation detail in @capgo/capacitor-social-login, @capgo/capacitor-passkey for the implementation detail in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric for the implementation detail in @capgo/capacitor-native-biometric, Two-factor authentication for the implementation detail in Two-factor authentication, and SSO (Enterprise) for the implementation detail in SSO (Enterprise).