Production-ready API documentation

Reliable cloud APIs for developer teams shipping at scale.

Integrate authentication, data, and event workflows through a consistent REST interface. Clear versioning, predictable responses, and practical examples help your team go from first request to production faster.

Read the docs Get API keys

200 OK

GET /v1/projects/{projectId}/usage?from=2026-03-01&to=2026-03-17

{
  "projectId": "proj_29f8",
  "period": {
    "from": "2026-03-01",
    "to": "2026-03-17"
  },
  "requests": 124934,
  "latencyMsP95": 182,
  "errors": {
    "rate": 0.0021,
    "count": 263
  },
  "status": "healthy"
}

Example response from the Usage endpoint. Full schema and error codes in the Endpoints section.

Overview

Cloud API Platform

A unified API layer for integrating authentication, data ingestion, event processing, and operational telemetry through predictable REST endpoints.

Key capabilities

Token-based API access with scoped permissions
Idempotent write operations for safe retries
Consistent pagination and filtering semantics
Webhook and event-stream support for async workflows

Base URL

All API requests must use HTTPS and include an API key.

https://api.cloudplatform.dev/v1

Environment-specific hosts (sandbox/production) are documented per account.

Response format expectations

Responses are JSON objects with a top-level data key for successful payloads.
Validation or runtime failures return error and request_id for traceability.
Timestamps use ISO-8601 UTC format (for example 2026-03-17T14:30:00Z).

Versioning

The platform uses path-based versioning (/v1, /v2). Breaking changes are released in new major versions and announced in advance.

Getting started

1. Generate an API key in your workspace.
2. Review Authentication and send a signed test request.
3. Call a read endpoint from Endpoints and verify response schema.
4. Validate operational behavior and edge cases via FAQ.

Security

Authentication

All API requests must be authenticated with an API key. Send your key as a Bearer token in the Authorization header over HTTPS.

API key authentication flow

Create an API key in your platform dashboard.
Store it in a secure environment variable, not in source code.
Include the key in every request as a Bearer token.
Rotate keys regularly and revoke compromised keys immediately.

Authorization header example

HTTP

Authorization: Bearer <YOUR_API_KEY>

Environment variable recommendation

Use environment variables to inject credentials at runtime. This reduces accidental key leaks in code repositories and CI logs.

Shell

export CLOUD_API_KEY="<YOUR_API_KEY>"

curl https://api.example.com/v1/projects \
  -H "Authorization: Bearer $CLOUD_API_KEY"

Security best practices

Never hardcode API keys in frontend bundles, mobile binaries, or public repositories.
Use least-privilege keys scoped to the minimum required permissions.
Rotate keys on a fixed schedule and after personnel or system access changes.
Audit request logs for unusual activity and unauthorized usage patterns.
Always use HTTPS; reject plaintext transport in all environments.

Common auth error responses

Authentication error response reference
Status	Meaning	Typical fix
401 Unauthorized	Missing, malformed, or invalid API key.	Verify Bearer format and key value; ensure key is active.
403 Forbidden	Key is valid but lacks required scope or access rights.	Update key permissions or use a key with correct project scope.

API Reference

Endpoints

Use the following endpoints to list projects, create new projects, and retrieve usage metrics. All responses are JSON and require a valid bearer token.

GET

`/v1/projects`

Returns a paginated list of projects available to the authenticated organization.

Sample request

curl -X GET "https://api.cloudplatform.dev/v1/projects?limit=20&cursor=proj_123" \
  -H "Authorization: Bearer <api_key>" \
  -H "Accept: application/json"

Request details

Query params: limit, cursor
Headers: Authorization, Accept: application/json

Sample response

{
  "data": [
    {
      "id": "proj_9f2a1",
      "name": "billing-service",
      "environment": "production",
      "created_at": "2026-02-08T10:24:31Z"
    }
  ],
  "pagination": {
    "next_cursor": "proj_a12b9",
    "limit": 20
  }
}

POST

`/v1/projects`

Creates a new project and returns the created resource with default settings.

Sample request

curl -X POST "https://api.cloudplatform.dev/v1/projects" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "analytics-worker",
    "environment": "staging"
  }'

Request details

Body fields: name (string), environment (enum)
Headers: Authorization, Content-Type: application/json

Sample response

{
  "id": "proj_c81de",
  "name": "analytics-worker",
  "environment": "staging",
  "status": "active",
  "created_at": "2026-03-17T09:14:22Z"
}

GET

`/v1/usage`

Retrieves usage aggregates for API requests, compute time, and transfer for a time window.

Sample request

curl -X GET "https://api.cloudplatform.dev/v1/usage?from=2026-03-01&to=2026-03-17&granularity=day" \
  -H "Authorization: Bearer <api_key>" \
  -H "Accept: application/json"

Request details

Query params: from, to, granularity
Response format: application/json

Sample response

{
  "range": {
    "from": "2026-03-01",
    "to": "2026-03-17",
    "granularity": "day"
  },
  "totals": {
    "requests": 184230,
    "compute_ms": 927400,
    "egress_mb": 4312
  }
}

Frequently asked questions

Quick answers for common integration topics. For full implementation details, see Authentication and Endpoints.

What are the default API rate limits?: Production keys start at 120 requests/min per project. Responses include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers.
Is a sandbox environment available?: Yes. Use sandbox credentials and the sandbox base URL to test flows safely. Sandbox data is isolated, synthetic, and may be reset without notice.
How is API versioning handled?: Versioning is path-based (for example, /v1). Breaking changes are released only in new major versions. Existing major versions receive a deprecation window and migration notes in Overview.
What happens when webhook delivery fails?: Failed deliveries are retried with exponential backoff for up to 24 hours. Endpoints must return a 2xx status to acknowledge receipt. Each retry includes the same event ID for idempotent processing.
Which support channels are available?: Use the support portal for ticketed issues, status page for incidents, and community chat for implementation questions. Include request IDs and timestamps to speed up investigation. For escalation paths, see the contact details.