API v1 · REST · JSON

Integrate the Cloud API with clear, working references.

Authenticate, call endpoints, and handle responses — organized so you can go from overview to a first successful request without guesswork.

Read the docs~5 min to first request
01 / Overviewv1

One API to provision, secure, and observe cloud resources.

A versioned REST interface with predictable JSON, scoped credentials, and copy-ready examples for every call.

ClientAuthEndpointJSON
  1. 01Platform

    Create and manage projects, compute instances, storage buckets, and event streams through a single base URL.

  2. 02Authentication

    API keys for servers and OAuth 2.0 tokens for user-facing apps, each scoped per project.

    Go to Authentication
  3. 03Endpoints

    Grouped by resource — /projects, /instances, /storage, /events — with methods, parameters, and status codes.

    Go to Endpoints
  4. 04Examples

    Every endpoint ships a curl request and a full JSON response you can copy straight into your client.

  5. 05FAQ

    Rate limits, error handling, pagination, and versioning answered in one place.

    Go to FAQ

02 · Getting access

Authentication#

Every call to the Cloud API is authorized with a short-lived bearer token issued from your API credentials. Set it up once, then reuse the same header on every endpoint.

  1. Create API credentials

    In the dashboard, open Settings → API Keys and generate a client_id and client_secret. Create separate pairs for sandbox and production.

  2. Exchange them for an access token

    Send your credentials to POST /oauth/token with grant_type=client_credentials. Tokens are valid for 3600 seconds; request a new one before expires_in elapses.

  3. Authorize each request

    Add the token to the Authorization header as Bearer <token>. Missing or expired tokens return 401 Unauthorized.

  4. Keep secrets server-side

    Never ship a client_secret in browser or mobile code, and never commit it to version control. Rotate keys immediately if one is exposed.

Example: authorized requestcURL
# 1. Request an access token
curl -X POST https://api.cloudapi.dev/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=$CLOUD_API_CLIENT_ID \
  -d client_secret=$CLOUD_API_CLIENT_SECRET

# 2. Call any endpoint with the token
curl https://api.cloudapi.dev/v1/projects \
  -H "Authorization: Bearer $CLOUD_API_TOKEN" \
  -H "Content-Type: application/json"

# 200 OK
{ "data": [ ... ], "request_id": "req_8f2c41" }

Authenticated? You can now call any endpoint.

Next: Endpoints

Reference · 03

Endpoints

The API is organized into four resource groups. Every path is versioned, returns JSON, and follows the same pagination, error, and authentication conventions.

Base URL
https://api.cloudapi.dev/v1
Format
application/json

  • Projects

    #

    Create and manage the top-level containers that own every other resource.

    GET/v1/projects

    Note: Paginated with cursor and limit; returns 20 items by default.

  • Deployments

    #

    Ship, roll back, and inspect service releases within a project.

    POST/v1/projects/{id}/deployments

    Note: Send an Idempotency-Key header so retries never create duplicate releases.

  • Storage

    #

    Upload, list, and retrieve objects in managed buckets.

    PUT/v1/buckets/{bucket}/objects/{key}

    Note: Objects larger than 100 MB should use the multipart upload flow.

  • Webhooks

    #

    Subscribe to platform events and receive them at your own URL.

    POST/v1/webhooks

    Note: Verify the X-Signature header on every delivery before processing.

Every endpoint requires a bearer token.Review AuthenticationCommon questions

Reference · FAQ

Common integration blockers#

Short, practical answers to the issues developers hit most often during integration.

5 answers

01

Why do my requests return 401 Unauthorized?

Send your key in the Authorization: Bearer <API_KEY> header — never as a query parameter. Confirm the key matches the environment you are calling (test keys fail against live), and refresh expired access tokens before retrying.

Review authentication
02

What are the rate limits, and what happens when I exceed them?

Each key allows 600 requests per minute by default. Over the limit you receive 429 with a Retry-After header. Track X-RateLimit-Remaining and back off exponentially instead of retrying immediately.

03

How is the API versioned?

The major version lives in the path, e.g. /v2/. Within a version we only ship additive changes — new fields and endpoints. Breaking changes arrive in a new major version, with at least 12 months of notice via the Sunset header.

04

How should my client handle errors?

Every error returns JSON with error.code, error.message, and request_id. Treat 4xx as client errors: fix the request rather than retrying (except 429). Retry 5xx with backoff, and send an Idempotency-Key on writes so retries are safe.

See response examples
05

Something still fails. Where do I start troubleshooting?

  1. a.Capture the X-Request-Id from the failing response.
  2. b.Reproduce the call with curl -v and compare it against the endpoint examples.
  3. c.Still blocked? Contact support with the request ID, timestamp, and endpoint path.

Didn't find your answer? Jump back to the reference.