API Quickstart — Getting Started

Get up and running with the GPCN™ API in under 10 minutes. This guide covers authentication, your first request, and the response patterns you'll see throughout the API.

Prerequisites

You'll need one of the following to authenticate:

An API key (recommended for scripts and integrations) -- create one from the portal under Account Settings > API Keys, or via the API after signing in
Account credentials (email + password) -- for session-based access

All examples use the base URL https://api.gpcn.com.

Authentication

The API supports two authentication methods. Pick the one that fits your use case.

Option 1: API Key (Recommended)

API keys are the simplest way to authenticate. Pass your key in the X-API-Key header:

curl https://api.gpcn.com/v1/resource/virtual-machines \
  -H "X-API-Key: gpcn_your_api_key_here"

Alternatively, you can use the Authorization: Bearer header with your API key (must have the gpcn_ prefix):

curl https://api.gpcn.com/v1/resource/virtual-machines \
  -H "Authorization: Bearer gpcn_your_api_key_here"

Option 2: Session-Based Auth

For interactive applications, sign in with email and password to get a session cookie:

# Step 1: Sign in
curl -X POST https://api.gpcn.com/v1/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

# Step 2: Complete 2FA (if prompted)
curl -X POST https://api.gpcn.com/v1/auth/two-factor/verify-totp \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -c cookies.txt \
  -d '{"code": "123456"}'

# Step 3: Use the session cookie for subsequent requests
curl https://api.gpcn.com/v1/resource/virtual-machines \
  -b cookies.txt

See Authentication → for examples in TypeScript, Python, Go, and C#.

Which Should I Use?

Method	Best for	Notes
API key	Scripts, CI/CD, server apps	Simplest setup, no 2FA flow needed
Session	Browser apps, interactive tools	Requires sign-in + 2FA, cookies expire

Your First Request

Let's list your virtual machines. This is the most common starting point.

curl https://api.gpcn.com/v1/resource/virtual-machines \
  -H "X-API-Key: gpcn_your_api_key_here"

See the API Reference → for examples in TypeScript, Python, Go, and C#.

Understanding Responses

Every GPCN™ API response follows a consistent structure.

Successful Response (Single Resource)

{
  "success": true,
  "message": "",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "web-server-01",
    "status": "Running"
  },
  "meta": null
}

Successful Response (List with Pagination)

{
  "success": true,
  "message": "",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "web-server-01"
    },
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "name": "db-server-01"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "pageSize": 10,
    "totalPages": 5,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Error Response

{
  "success": false,
  "message": "Virtual machine not found",
  "error": {
    "code": "NOT_FOUND",
    "statusCode": 404,
    "details": null
  }
}

Check success first in your code. If it's false, the error object tells you what went wrong.

Pagination

All list endpoints return paginated results. Control pagination with query parameters.

Query Parameters

Parameter	Default	Description
`page`	`1`	Page number (1-indexed)
`limit`	`10`	Items per page
`sort`	varies	Sort field and direction, e.g. `name:asc`
`search`	--	Free-text search across supported fields

Paginating Through Results

# First page
curl "https://api.gpcn.com/v1/resource/virtual-machines?page=1&limit=10" \
  -H "X-API-Key: gpcn_your_api_key_here"

# Next page
curl "https://api.gpcn.com/v1/resource/virtual-machines?page=2&limit=10" \
  -H "X-API-Key: gpcn_your_api_key_here"

Sorting and Searching

# Sort by name, ascending
curl "https://api.gpcn.com/v1/resource/virtual-machines?sort=name:asc" \
  -H "X-API-Key: gpcn_your_api_key_here"

# Search for VMs containing "web"
curl "https://api.gpcn.com/v1/resource/virtual-machines?search=web" \
  -H "X-API-Key: gpcn_your_api_key_here"

Error Handling

HTTP Status Codes

The API uses standard HTTP status codes:

Code	Meaning	When you'll see it
`200`	OK	Successful GET, PUT
`201`	Created	Successful POST (resource created)
`202`	Accepted	Async operation started (VM creation, deletion)
`401`	Unauthorized	Invalid or missing credentials
`403`	Forbidden	You don't have permission
`404`	Not Found	Resource doesn't exist
`422`	Validation Error	Request body failed validation
`429`	Rate Limited	Too many requests

Rate Limits

The API enforces rate limits to protect the platform:

Sign-in: 15 requests per 15 minutes
General API: 100 requests per 60 seconds (default)

When you hit a rate limit, the response includes headers telling you when you can retry:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1703433600

Async Operations

Some operations (like creating or deleting VMs) are asynchronous. They return 202 Accepted with a job ID you can poll:

{
  "success": true,
  "message": "Operation initiated successfully",
  "data": {
    "jobs": ["job-uuid-here"]
  },
  "meta": null
}

Check job status at POST /v1/resource/jobs with the job ID.

Explore the Full API

For a complete list of endpoints, request/response schemas, and interactive testing, visit the API Reference.

Next Steps

Now that you can authenticate and make basic requests, explore these topics:

Portal Quickstart — get oriented in the web dashboard

Developer Resources

Authentication