Overview Authentication Endpoints FAQ

API Documentation · v1

Cloud API Platform Overview

A single REST interface for provisioning, monitoring, and managing cloud resources programmatically. Every endpoint returns structured JSON and follows the same authentication and error-handling conventions, so you can integrate once and reuse the pattern everywhere.

quickstart.sh

# Fetch platform status with your API key
curl -X GET https://api.cloudplatform.dev/v1/status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

REST Endpoints: Resource-oriented URLs and standard HTTP verbs for every operation.
JSON Responses: Consistent, predictable payloads with typed fields on every response.
API Keys: Scoped, revocable credentials for authenticating every request.
Predictable Errors: Structured error codes and messages so failures are easy to handle.

Authentication

Authenticate your requests

Every request to the API must be authenticated with an API key. Keys are issued per project and scoped to the environment they were created in. Requests without a valid key are rejected before any resource is processed.

API keys

Generate a key from your dashboard under Settings → API Keys. Each key is prefixed with sk_live_ or sk_test_ depending on environment.

All requests are made against the base URL:

https://api.cloudplatform.dev/v1

Authorization header

Pass your API key as a Bearer token in the Authorization header on every request.

bash — request example

curl -X GET https://api.cloudplatform.dev/v1/resources \
  -H "Authorization: Bearer sk_live_51Hf..." \
  -H "Content-Type: application/json"

json — response 200

{
  "id": "res_8fJ2kLp",
  "status": "active",
  "created_at": "2026-07-08T09:14:00Z"
}

Security notes

Never expose API keys in client-side code, mobile apps, or public repositories.
All requests must use HTTPS. Plain HTTP requests are rejected outright.
Rotate keys periodically and immediately revoke any key you suspect is compromised.
Use scoped, environment-specific keys rather than a single shared key across projects.

Common authentication errors

Status	Meaning	Fix
401 Unauthorized	Missing, malformed, or invalid API key	Verify the header format and confirm the key is active
403 Forbidden	Key is valid but lacks permission for this resource	Check the key's scopes and environment
429 Too Many Requests	Rate limit exceeded for this key	Implement exponential backoff and retry logic

API Reference

Endpoints

Explore the core resources exposed by the platform. Every endpoint accepts and returns JSON, and requires a valid bearer token as described in the Authentication guide.

GET /v1/projects

List all projects associated with your account, with optional filtering and pagination.

Query Parameters

Name	Type	Description
limit	integer	Max results per page (default 20)
offset	integer	Number of records to skip
status	string	Filter by project status

Sample Request

curl -H "Authorization: Bearer $TOKEN" \
  https://api.example.com/v1/projects?limit=20

200 OK — returns an array of project objects and a nextCursor for pagination.

POST /v1/projects

Create a new project under your account.

Body Parameters

Name	Type	Description
name	string, required	Project display name
region	string	Deployment region, defaults to us-east
tags	array<string>	Optional labels for organization

Sample Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-project","region":"us-east"}' \
  https://api.example.com/v1/projects

201 Created — returns the newly created project object, including its generated id.

GET /v1/usage

Retrieve aggregated usage metrics for a project over a given time period.

Query Parameters

Name	Type	Description
projectId	string, required	Target project identifier
from	string	Start date, ISO 8601 format
to	string	End date, ISO 8601 format

Sample Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.example.com/v1/usage?projectId=proj_123&from=2026-06-01&to=2026-07-01"

200 OK — returns a usage summary with request counts, bandwidth, and compute hours.

DELETE /v1/projects/{id}

Permanently delete a project and all of its associated resources.

Path Parameters

Name	Type	Description
id	string, required	Unique identifier of the project to delete

Sample Request

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://api.example.com/v1/projects/proj_123

204 No Content — the project and all associated resources are permanently deleted. This action cannot be undone.

FAQ

Frequently asked questions

Common technical questions about rate limits, versioning, error handling, and platform behavior. If your question isn't answered here, check the Overview and Authentication sections above.

What are the API rate limits?

Requests are limited to 1,000 per minute per API key on standard plans. Limit status is returned on every response via headers:

X-RateLimit-Limit: 1000 · X-RateLimit-Remaining: 842

Exceeding the limit returns a 429 Too Many Requests response with a Retry-After header.

How does API versioning work?

The API is versioned via the URL path, e.g. /v1/ and /v2/. Breaking changes are only introduced in a new major version. Deprecated versions remain available for 12 months, with sunset dates announced in the changelog.

How are errors formatted and handled?

All errors return a consistent JSON payload with an HTTP status code, machine-readable code, and message:

{"error": {"code": "invalid_request", "message": "..."}}

4xx codes indicate client errors, 5xx indicate server-side failures. Retry 5xx responses with exponential backoff.

Is a sandbox environment available?

Yes. A fully isolated sandbox is available at sandbox.api.example.com using test API keys prefixed with sk_test_. Sandbox data resets every 24 hours and no requests reach production systems.

Does the platform support webhooks?

Yes. Webhooks can be configured per event type from the dashboard. Payloads are signed with an HMAC-SHA256 signature in the X-Signature header, and failed deliveries are retried up to 5 times with exponential backoff before being marked dead.

How do I rotate or revoke API keys?

Generate a new key from the dashboard, update your integration, then revoke the old key. Both keys remain valid for a 24-hour grace period to allow zero-downtime rotation. Revoked keys immediately return 401 Unauthorized.