Skip to main content
All responses are JSON. This page describes the response shapes you will see across endpoints.

​
Content Type

  • Success: Content-Type: application/json
  • Errors: Content-Type: application/json (same as success; distinguish by HTTP status code)

​
Success Responses

​
List Endpoints (Collections)

These list endpoints use this shape: List workspaces, List products, List items, List properties. 
{
  "items": [
    { "id": "...", "name": "...", ... }
  ],
  "count": 2
}
FieldTypeDescription
itemsarrayArray of resource objects for the current page
countintegerNumber of items in this response (page size)
count is the length of items, not the total number of resources. Use pagination parameters to request more pages.

​
Single Resource Endpoints

Endpoints that return one resource (e.g. get workspace by ID, get product by ID) return the resource object directly: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "readable_id": "ws-001",
  "name": "My Workspace"
}
No wrapper object; the response body is the resource.

​
Common Resource Fields

Many resources include:
  • id: UUID, stable unique identifier; use this for API calls.
  • readable_id: Human-readable identifier (e.g. ws-001, prod-abc); is changeable inside Poelis.

​
Error Responses

When the request fails, the API returns a JSON error body and a non-2xx status code. Structure: 
{
  "error": "error_code",
  "message": "Error message",
  "details": {
    "field": "additional context"
  }
}
FieldTypeDescription
errorstringMachine-readable code (e.g. validation_error)
messagestringError message
detailsobjectOptional; extra context (e.g. field, retry_after)
details may be omitted for some errors. Always check the HTTP status code and error for handling logic. See Status Codes and Error Handling for all codes and examples.

​
Response Headers

  • X-Request-ID: Unique ID for the request. Include it when contacting support about an error.
  • Retry-After: Present on 429 Too Many Requests; seconds to wait before retrying (e.g. "60").
  • X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset: Present on all responses; on 429, X-RateLimit-Remaining is "0" and X-RateLimit-Reset is the Unix timestamp (seconds) when the window resets.