Customer Documentation

Bocada Cloud API

Documentation for reading organizations, connections, protected resources, backup jobs, and backup-job timelines from Bocada Cloud. Start here to make your first request, then use the full reference below to build your integration.

Authentication Pagination Errors Core Resources

Base URL

Use this base URL for every request in this guide.

The endpoint reference below is relative to the host serving this documentation. Append the versioned path shown for each operation to the base URL below.

Base URL Loading...

First Call

Start with a lightweight status request.

GET /api/v1/system/status is the recommended first request because it confirms your API key is accepted and shows the scopes attached to that key.

GET /api/v1/system/status
X-Api-Key: bc_live_your_secret_here
Accept: application/json

Authentication

Include your API key in the X-Api-Key header on every request. Keep keys in server-side configuration, secret managers, or automation vaults rather than in browser code, shared notes, or email threads.

If you need end-to-end traceability for a scheduled job or export, send X-Request-Id with your own unique value. Bocada returns that identifier with the response so you can correlate runs across your logs and support conversations.

A simple way to verify a new integration is to call GET /api/v1/system/status before moving on to business endpoints. Once that call succeeds, the same header pattern applies everywhere else in v1.

Pagination

List endpoints return data in slices so you can process large inventories and job histories without pulling everything into a single response. This keeps scheduled exports, dashboards, and synchronization jobs predictable as your dataset grows.

Start without a cursor and choose a pageSize that fits your workflow. Many customers begin with 25 to 100 records per request, while larger backfill jobs can safely use values up to 200.

If pagination.nextCursor is present, repeat the same request with that value to continue from the last result returned. Reuse the cursor exactly as given and stop when nextCursor is no longer returned.

Errors

When a request cannot be completed, the response includes code, message, optional details, and requestId. Use code for programmatic handling and message/requestId for operator logs and support follow-up.

Common outcomes are authentication_failed when the key is missing or invalid, bad_request when a filter or sort value needs to be corrected, not_found when a record is outside the data visible to your key, and rate_limit_exceeded when your client needs to slow down.

When you receive a throttling response, inspect RateLimit-Limit and RateLimit-Reset before retrying. A small backoff strategy around those headers makes scheduled integrations much more reliable.

Core Resources

Organizations describe the customer or business scope available to your key. Connections represent the backup systems integrated with Bocada Cloud, and resources represent the protected assets tracked through those connections.

Backup jobs give you execution history for those protected assets, while event timelines give you the messages, warnings, and error entries associated with an individual backup job.

The v1 surface is read-only, so integrations can safely query and synchronize data without changing protected objects. Most implementations follow a simple pattern: list resources, store the public identifiers you care about, then use detail and timeline endpoints for deeper views.