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, or send it as Authorization: Bearer YOUR_API_KEY.

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 with the raw key (no Bearer prefix) is still accepted for legacy integrations, but x-api-key is the recommended header for all key types, including secure hashed keys.

AI agents and other OAuth clients can get a key through OAuth 2.0 (authorization code with PKCE and dynamic client registration). The issuer is https://capgo.app, with metadata at https://capgo.app/.well-known/oauth-authorization-server. The user picks which organizations to grant, and the access token is a Capgo API key sent as a Bearer token.

Versioning

The API is versioned by date. Pin a version with the capgo_api request header:

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

Without the header you get the default version, currently 2025-10-01. Changes within a version are additive: new endpoints, new optional parameters and new response fields. A breaking change ships as a new dated version, and clients pinned to an older date keep the old behavior. An unknown or malformed version returns 400 unsupported_capgo_api_version or 400 invalid_capgo_api_version.

Removing an operation or field is a breaking change, so it only happens in a new dated version. Nothing is deprecated today. When something is, the operation will be marked deprecated: true in the OpenAPI spec, its responses will carry a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) with the date the old behavior ends, and the change will be announced in the release notes.

Rate Limiting

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

• 2,000 requests per minute per API key
• 20,000 requests per minute per API key on bundle upload routes
• 20 invalid API keys per IP address within 15 minutes, after which the IP is blocked for 15 minutes

Every response reports the quota with the RateLimit-Policy and RateLimit headers (IETF draft):

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

q is the quota, w the window in seconds, r the requests left and t the seconds until the window resets. If you exceed a limit, you’ll receive a 429 (Too Many Requests) response with a Retry-After header in seconds.

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 a machine-readable error code, a human-readable message, and optional moreInfo details.

Example success response:

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

Example error response:

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

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).