Global Private Cloud Network™ (GPCN™) API

Quick Start

1. Click Authorize (top right)
2. Enter your API key: gpcn_your_key_here
3. Click Authorize, then Close
4. Try any endpoint!

Authentication

API Key (required for Swagger UI and programmatic access)

X-API-Key: gpcn_abc123...

Create and manage API keys in the GPCN Portal under Settings → API Keys, or via the /auth/api-keys/me endpoints if you have an existing session.

API keys support:

• Role-based permissions (inherit your role or scoped permissions)
• Rate limiting (configurable per key)
• Optional expiration

Note: Browser-based applications use session cookies via /auth/sign-in/email. This is not available in Swagger UI.

Response Format

{
  "success": true,
  "message": "",
  "data": { ... },
  "meta": { "total": 100, "page": 1, "pageSize": 10, ... }
}

Query Parameters

Error Codes

Versioning

The API uses URL path versioning (/v1/). Breaking changes will increment the version number. Non-breaking additions (new endpoints, optional fields) may be added without version change.

Rate Limits

API keys are subject to rate limiting:

• Default: 1000 requests per minute
• Custom limits can be configured per API key
• Rate limit headers are returned with each response:
  • X-RateLimit-Limit: Maximum requests per window
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when window resets
• When rate limited, you'll receive a 429 status code

Async Operations

Long-running operations (VM creation, deletion, resize) return 202 Accepted with a job tracking object:

{
  "success": true,
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "stage": "initializing",
    "progressPercentage": 0
  }
}

Poll GET /resource-jobs/status?jobIds={jobId} to track progress until isCompleted is true.

Entity Context

Most endpoints operate within an entity context:

• Defaults to your primary entity if not specified
• Use entityId query parameter to target a specific entity
• Cross-entity access requires hierarchy permissions (parent can access child entities)