Warning: JavaScript is not enabled or not loaded. Please enable JavaScript for the best experience.
Cloud API Platform

Cloud API Platform

Documentation

Cloud API Platform Cloud API Platform

Overview

The cloud API platform is a comprehensive resource management and integration engine designed for developers, DevOps engineers, and technical teams who need to build scalable applications with reliable infrastructure automation.

Whether you're provisioning compute resources, managing configurations, monitoring system health, or integrating webhooks into your workflow, this platform provides a unified, developer-friendly API with predictable JSON responses and straightforward authentication.

What You Can Build

Teams use this platform to build a range of solutions across infrastructure, deployment, and automation:

  • → Automated deployment pipelines — trigger resource provisioning and configuration updates
  • → Real-time monitoring dashboards — stream analytics and health metrics to your own UI
  • → Custom integrations — connect to third-party systems via webhooks and API calls
  • → Infrastructure as code — manage environments, versions, and resources programmatically

Core Capabilities

Resource Management

Create, update, and delete resources with full lifecycle control and version tracking.

Webhooks

Receive real-time notifications for resource changes and system events.

Analytics & Insights

Access detailed metrics, usage analytics, and performance data for your resources.

Multi-Environment Support

Separate development, staging, and production environments with isolated configurations.

Predictable JSON Responses

Consistent response format across all endpoints for reliable error handling and parsing.

Rate Limiting & Quotas

Transparent rate limits with clear headers and quota management per API key.

Base URL

All API requests are made to:

https://api.cloud-platform.io/v1

Quick Start in 4 Steps

1

Get Your API Key

Head to the Authentication section and generate a new API key from your account dashboard. You'll use this for all requests.

2

Explore Available Endpoints

Visit the Endpoints documentation to see all available resources. Each endpoint includes example requests and responses.

3

Make Your First Request

Use your API key in the Authorization header and make a test request to any endpoint. Check the response format and error handling patterns.

4

Set Up Webhooks & Monitoring

Configure webhooks for resource events and enable analytics to track usage. See the FAQ for common implementation patterns.

Authentication

All API requests require authentication using an API key or Bearer token. The platform supports both methods, with Bearer tokens recommended for production environments.

Authentication Methods

API Key

API keys are the simplest way to authenticate. Include your API key in the X-API-Key header with every request.

curl
curl -H "X-API-Key: sk_live_1a2b3c4d5e6f7g8h9i0j" \
  https://api.platform.com/v1/data

Best for: Development environments, server-to-server communication, testing.

Bearer Token

Bearer tokens are recommended for production. Include the token in the Authorization header with the Bearer prefix.

curl
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://api.platform.com/v1/data

Best for: Production environments, user-facing applications, token rotation scenarios.

Authorization Header

The Authorization header must be included in every authenticated request. The header format depends on your authentication method:

API Key Format
X-API-Key: sk_live_1a2b3c4d5e6f7g8h9i0j
Bearer Token Format
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Note: Include the header on every request to protected endpoints. Requests without valid authentication will return a 401 Unauthorized error.

Test & Production Environments

Test Environment

Use test keys (prefixed with sk_test_) for development and testing.

https://api-test.platform.com/v1

Production Environment

Use live keys (prefixed with sk_live_) for production traffic.

https://api.platform.com/v1

Never use test keys in production, and never expose live keys in client-side code or version control.

Token Rotation & Security

✓
Regular Rotation: Rotate Bearer tokens every 30–90 days depending on your security policy.
✓
Secure Storage: Store credentials in environment variables or secure vaults, never hardcode them.
✓
HTTPS Only: Always use HTTPS to prevent token interception over the network.
✗
Avoid Client-Side: Do not store or transmit credentials from browsers or mobile apps without backend relay.

Common Authentication Errors

401

Unauthorized

Missing, invalid, or expired authentication credentials.

  • Check that the Authorization or X-API-Key header is present
  • Verify the token or key is not expired
  • Confirm you're using the correct environment (test vs. production)
403

Forbidden

Credentials are valid but lack permission for this resource.

  • Check your token's scopes and permissions
  • Ensure the API key has access to the requested endpoint
  • Contact support if you believe this is incorrect
429

Too Many Requests

Rate limit exceeded. See the rate limiting section for details.

  • Implement exponential backoff for retries
  • Check rate limit headers in the response
  • Consider upgrading your plan for higher limits

Quick Reference

API Key Header: X-API-Key
Bearer Token Header: Authorization: Bearer <token>
Test Endpoint: https://api-test.platform.com/v1
Live Endpoint: https://api.platform.com/v1
Token Expiry: Check response headers

Endpoints

Complete reference for all API endpoints with request/response patterns, conventions, and error handling.

Overview

Our API follows REST conventions and returns JSON for all requests and responses. Every endpoint requires authentication using a Bearer token (see Authentication section). Responses include standard HTTP status codes, pagination metadata, and detailed error information.

Request & Response

All endpoints accept and return JSON. Include the Authorization header with your Bearer token on every request.

Rate Limiting

100 requests per minute per token. Response headers include X-RateLimit-Remaining and X-RateLimit-Reset.

Pagination

List endpoints support limit/offset pagination. Default limit is 20, maximum is 100. Use next_cursor for cursor-based navigation.

Error Handling

HTTP status codes with JSON error details. All errors include code, message, and request_id for debugging.

Projects

GET /api/v1/projects

Retrieve all projects in your workspace

POST /api/v1/projects

Create a new project with name, description, and initial settings

GET /api/v1/projects/:id

Retrieve a specific project by ID with full metadata

PATCH /api/v1/projects/:id

Update project details like name, description, or settings

DELETE /api/v1/projects/:id

Permanently delete a project and all associated data

Environments

GET /api/v1/projects/:projectId/environments

List all environments (staging, production, etc.) in a project

POST /api/v1/projects/:projectId/environments

Create a new environment with configuration variables

GET /api/v1/projects/:projectId/environments/:envId

Get detailed information for a specific environment

PATCH /api/v1/projects/:projectId/environments/:envId

Update environment configuration and variables

DELETE /api/v1/projects/:projectId/environments/:envId

Remove an environment and its associated resources

Deployments

GET /api/v1/projects/:projectId/deployments

Retrieve all deployments with filters for environment and status

POST /api/v1/projects/:projectId/deployments

Trigger a new deployment with specified source and target environment

GET /api/v1/projects/:projectId/deployments/:deploymentId

Get status, logs, and details of a specific deployment

POST /api/v1/projects/:projectId/deployments/:deploymentId/rollback

Rollback to a previous stable deployment version

Usage & Analytics

GET /api/v1/projects/:projectId/usage

Get current usage metrics, API call counts, and quota information

GET /api/v1/projects/:projectId/logs

Retrieve API request logs with filtering, sorting, and pagination

GET /api/v1/projects/:projectId/metrics

Query performance metrics, response times, and error rates

Error Responses

All error responses follow this structure with appropriate HTTP status codes:

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: api_key",
    "details": "The api_key parameter is required for all requests",
    "request_id": "req_1h2g3h4i5j6k7l8m"
  }
}
400 Bad Request

Invalid request parameters, malformed JSON, or validation errors

401 Unauthorized

Missing, invalid, or expired authentication token

403 Forbidden

Authenticated but lacks permission for this resource

404 Not Found

Requested resource does not exist or has been deleted

429 Too Many Requests

Rate limit exceeded. Check X-RateLimit-Reset header for retry time

500 Server Error

Server error. Use request_id to contact support team

Frequently Asked Questions

Quick answers to common developer questions about API usage, authentication, rate limits, and implementation.

Is there a sandbox environment for testing?

Yes, a dedicated sandbox environment is available at https://sandbox-api.platform.dev. Use your sandbox credentials (obtained via dashboard) to authenticate. Sandbox data is isolated and reset weekly. Rate limits are relaxed for testing purposes.

What are the rate limits for API requests?

Rate limits depend on your plan:

  • Starter: 100 requests/minute
  • Professional: 1,000 requests/minute
  • Enterprise: Custom limits

Rate limit information is returned in response headers (X-RateLimit-Remaining, X-RateLimit-Reset). Exceeding limits returns a 429 Too Many Requests response.

How does API versioning work?

The API uses URL-based versioning. All endpoints are prefixed with the version (e.g., /v1/resources, /v2/resources). Major versions are maintained for a minimum of 12 months after a new version is released. Deprecation notices are announced 6 months in advance via email and dashboard alerts.

How do webhook retries work?

Webhooks are retried with exponential backoff if the endpoint returns a non-2xx status or times out:

  • Attempt 1: Immediate
  • Attempt 2: 5 seconds
  • Attempt 3: 30 seconds
  • Attempt 4: 2 minutes
  • Attempt 5: 5 minutes

After 5 failed attempts, the webhook is marked as failed. You can manually retry or re-deliver webhooks from the dashboard. Webhook delivery logs are retained for 30 days.

Are SDKs available for popular languages?

Official SDKs are available for:

  • Python (PyPI)
  • Node.js (npm)
  • Go (GitHub)
  • Java (Maven)
  • C# (.NET)

Community SDKs for Ruby, PHP, and Rust are available on GitHub. All SDKs support the latest API version and include built-in retry logic, request validation, and comprehensive documentation.

What support options are available?

Support tiers vary by plan:

  • Starter: Community forums, email (48-hour response)
  • Professional: Email/Slack (8-hour response), priority queue
  • Enterprise: Dedicated support channel, 1-hour response, technical account manager

All plans include access to our documentation, API reference, and code examples. Security-related issues should be reported to [email protected].

Which authentication methods are supported?

Two primary authentication methods are supported:

  • API Keys: Simple, suitable for server-to-server communication
  • OAuth 2.0: Recommended for user-facing applications and third-party integrations

See the Authentication section for detailed setup instructions. All API requests must include authentication headers. Credentials are never logged or stored in plain text.

How should I handle API errors?

All API error responses follow a standard format with error, message, and request_id fields. Use HTTP status codes to determine error type (4xx for client errors, 5xx for server errors). For 5xx errors, implement exponential backoff and retry logic. Always log the request_id for debugging support requests.

How do I handle large datasets or pagination?

List endpoints support cursor-based pagination with limit and cursor query parameters. Default limit is 50 items, maximum is 500. Responses include a next_cursor field for fetching the next page. For efficient data export, use the batch export endpoints which support date range filtering and return compressed JSON or CSV.

What is the data retention policy?

Data retention depends on resource type and account status:

  • Active accounts: All data retained indefinitely (configurable)
  • Deleted accounts: Data deleted within 30 days
  • Logs/Audit trails: Retained for 90 days (Enterprise: 1 year)
  • Webhook delivery logs: Retained for 30 days

Export your data anytime via the dashboard or API. Contact support for data recovery or custom retention requirements.

Still have questions?

Check the Overview, Authentication, and Endpoints sections for more details, or contact support at [email protected].