API Docs

Cloud API reference designed for fast implementation

Clear authentication guidance, concise endpoint summaries, and predictable response formats. Everything you need to integrate quickly without leaving the docs.

Quick start v2

curl -X POST https://api.cloud.example/v2/auth/token \
  -H "x-api-key: $CLOUD_API_KEY" \
  -d '{"scope":"read:projects"}'

Returns a scoped bearer token for subsequent requests.

Jump to

Overview /overview Authentication /auth Endpoints /endpoints FAQ /faq

Overview

Cloud API Platform for reliable data workflows

This platform provides a consistent REST interface for streaming, querying, and synchronizing cloud data across services. Build integrations faster with predictable resources, versioned endpoints, and production-grade observability.

Key capabilities

Unified endpoints for events, storage, and analytics pipelines
Schema-first responses with strict typing and pagination
Idempotent writes and replay-safe ingestion workflows
Webhook delivery with retry controls and signatures

Common use cases

Powering real-time dashboards with streaming events
Syncing customer data between SaaS systems
Auditable data exports with versioned snapshots
Secure partner integrations with scoped API keys

Core concepts

Projects isolate data environments and control resource quotas.

Namespaces group related endpoints and provide clear ownership boundaries.

Resources are versioned objects with stable identifiers and audit trails.

Quick start base URL

Use the latest stable API version:

https://api.cloudplatform.dev/v1

See Authentication for token setup and required headers.

Why developers choose this API

Predictable integrations

Consistent response shapes, explicit error codes, and detailed request tracing.

Operational clarity

Built-in rate metrics, usage dashboards, and CLI support for deployments.

Security-first

Scoped keys, signed webhooks, and audited access logs.

Fast onboarding

Clear docs, tested SDKs, and step-by-step examples.

Security

Authentication

All requests require an API key or bearer token. Tokens are scoped by environment and can be rotated without downtime.

API keys

Use a server-side API key for back-end integrations. Keys are tied to a workspace and inherit workspace permissions.

Authorization: ApiKey <your_key>

Bearer tokens

Use OAuth or short-lived bearer tokens for user-facing or delegated access. Tokens are validated on every request.

Authorization: Bearer <token>

Best practices

Store secrets in a server-side vault; never ship keys to the client.
Rotate tokens regularly and revoke compromised credentials immediately.
Limit scope by environment and enable IP allowlisting where possible.

Example request

cURL

curl -X GET "https://api.nimbuscloud.com/v1/projects"
  -H "Authorization: Bearer <token>"
  -H "Accept: application/json"

Every endpoint returns 401 when credentials are missing or invalid.

Endpoints

Reference summary for core resources

Below are the most used API resources with request/response expectations, status codes, and pagination notes. All endpoints are JSON over HTTPS and require a valid bearer token.

Key endpoints

Accept: application/json

GET /v2/projects

List projects visible to the token. Supports pagination and filtering by owner or tag.

Query: page, page_size, owner_id, tag

200: array of projects + metadata

POST /v2/projects

Create a new project with name, region, and optional webhook settings.

Body: name, region, webhook_url?

201: project object

GET /v2/projects/{id}

Fetch a single project by identifier. Returns full settings and status.

Path: id

200: project object

PATCH /v2/projects/{id}

Update mutable fields such as display name, tags, or webhooks.

Body: name?, tags?, webhook_url?

200: updated project

GET /v2/usage

Retrieve aggregated usage metrics for a time window.

Query: from, to, granularity

200: metrics series

POST /v2/tokens

Create a scoped API token for automation or CI pipelines.

Body: label, scopes[], expires_at?

201: token object (one-time secret)

Request & response concepts

Content type: All requests and responses use application/json.

Idempotency: Provide Idempotency-Key on POST to avoid duplicates.

Rate limits: 600 req/min per token, returned via X-RateLimit-* headers.

Status codes: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests, 500 Server Error.

Errors: Consistent JSON payload with error.code, error.message, and request_id.

Pagination & filtering

List endpoints return a meta object with page, page_size, and total. Use page_size up to 200.

Filtering follows the pattern ?filter[field]=value and supports multiple fields. For tag arrays, send ?filter[tag][]=alpha&filter[tag][]=beta.

Sort with ?sort=created_at or descending ?sort=-created_at.

Developer FAQ

Frequently asked questions

Quick answers to common integration questions. Each response is designed for fast scanning and direct implementation.

What are the default rate limits?

Standard accounts receive 600 requests per minute per API key. Burst traffic is allowed up to 2x for 30 seconds before throttling. Limits are returned in the response headers for every request.

Which environments are available?

Use sandbox for testing and production for live traffic. Base URLs differ by subdomain; the request schema is identical between environments.

Why am I getting authentication errors?

Ensure the Authorization: Bearer <token> header is present and the token has not expired. Sandbox keys do not work against production endpoints.

How is API versioning handled?

Versioning is path-based (e.g., /v1/). We maintain one active version and one deprecated version with 6 months of overlap.

What do error responses look like?

Errors are JSON with code, message, and optional details. HTTP status codes follow RFC 9110 conventions.

What support should we expect?

Enterprise plans include 24/7 coverage with a 1-hour initial response SLA. Standard plans receive business-hours support with a 1-business-day response target.