Reference

API Conventions

Conventions shared across all GPCN™ API endpoints, including request format, response structure, pagination, and error handling.

Base URL

All API endpoints are served under a versioned base URL:

https://api.gpcn.com/v1

Request Format

All request bodies must be JSON. Include the Content-Type header with every request that sends a body.

curl -X POST https://api.gpcn.com/v1/resource/virtual-machines \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gpcn_your_api_key_here" \
  -d '{"name": "my-vm", "image": "ubuntu-22.04"}'

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

Response Format

Success Responses

All successful responses wrap the payload in a standard structure:

{
  "success": true,
  "data": { },
  "meta": { }
}
  • data contains the response payload (object or array)
  • meta is included for paginated list endpoints (see Pagination)

Error Responses

Errors follow a consistent structure:

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human-readable description of what went wrong"
}
  • error is a machine-readable code you can match against (see Error Codes)
  • message is a human-readable explanation suitable for logging

HTTP Status Codes

Status Meaning When you'll see it
200 OK Successful GET, PUT, or general success
201 Created Resource created via POST
202 Accepted Async operation started (includes jobId)
204 No Content Successful DELETE (no response body)
400 Bad Request Validation error or malformed request
401 Unauthorized Missing or invalid authentication
403 Forbidden Authenticated but lacking permission
404 Not Found Resource doesn't exist
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Something went wrong on our end

Pagination

List endpoints return paginated results. Control pagination with query parameters.

Query Parameters

Parameter Type Default Description
page integer 1 Page number (1-indexed)
limit integer 10 Items per page

Response Meta

Paginated responses include a meta object:

{
  "success": true,
  "data": [ ],
  "meta": {
    "total": 150,
    "page": 1,
    "pageSize": 10,
    "totalPages": 15,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Example: Paginating Results 

# Get page 2, 25 items per page
curl "https://api.gpcn.com/v1/resource/virtual-machines?page=2&limit=25" \
  -H "X-API-Key: gpcn_your_api_key_here"

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

Sorting

Sort list results with the sort query parameter. The format is field:direction.

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

# Sort by creation date, newest first
curl "https://api.gpcn.com/v1/resource/virtual-machines?sort=createdAt:desc" \
  -H "X-API-Key: gpcn_your_api_key_here"

Available sort directions are asc and desc. The sortable fields depend on the endpoint.

Searching

Use the search query parameter to filter results by a text term. The search is applied across fields relevant to the resource.

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

Search is case-insensitive and matches partial strings.

Filtering

Filter results by specific field values using query parameters.

# Filter by entity
curl "https://api.gpcn.com/v1/resource/virtual-machines?entityId=abc-123" \
  -H "X-API-Key: gpcn_your_api_key_here"

Available filters vary by endpoint. Common filters include entityId and teamId.

Combining Query Parameters

You can combine pagination, sorting, searching, and filtering in a single request:

curl "https://api.gpcn.com/v1/resource/virtual-machines?page=1&limit=20&sort=name:asc&search=web" \
  -H "X-API-Key: gpcn_your_api_key_here"

Async Operations

Some operations (like creating or deleting VMs) are asynchronous. These return 202 Accepted with a jobId you can use to track progress.

Response 

{
  "success": true,
  "data": {
    "jobId": "job-uuid-here"
  }
}

Polling for Completion

After receiving a 202, poll the job endpoint to check if the operation has completed. See Async Operations → for the full polling pattern and job status reference.

Troubleshooting

Common mistakes when working with GPCN™ API conventions:

Issue Solution
400 error when sorting — sort=name without direction The sort parameter requires the format field:direction. Use sort=name:asc or sort=name:desc.
400 error — request body sent as form data All request bodies must be JSON. Set the Content-Type: application/json header on every POST/PUT/PATCH request.
Empty data array on a page beyond the last Page numbers are 1-indexed. Check meta.totalPages before requesting further pages; requesting page > totalPages returns an empty array, not an error.
401 Unauthorized despite providing a key Verify the header name is X-API-Key (case-sensitive) and the key value includes the gpcn_ prefix.
limit set to 0 or a negative number limit must be a positive integer. The default is 10; the maximum depends on the endpoint.
Sort field not applying — no visible change in order Not all fields are sortable on every endpoint. Check the endpoint's documentation for its list of sortable fields.
Content-Type header included on GET or DELETE Only include Content-Type: application/json on requests that carry a body (POST, PUT, PATCH). Including it on GET or DELETE may cause unexpected behavior.
Search returns no results for an exact ID The search parameter performs partial text matching across display fields. To look up a resource by ID, use the direct resource path (/resource/virtual-machines/{id}) instead.
Combining sort with search returns unexpected order When both are provided, search filters first, then sort orders the filtered results. Ensure your sort field is relevant to the filtered dataset.

Next Steps

Previous
Authentication
Next
Rate Limiting