Response Format

Every hzel API response uses one of two JSON shapes.

Success

{
  "data": <payload>
}

data is the resource or value returned by the endpoint. Its type varies per endpoint and is documented on each endpoint’s page.

Example — single resource:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "hostname": "my-container",
    "state": "running"
  }
}

Example — list:

{
  "data": [
    { "id": "…", "hostname": "box-a", "state": "running" },
    { "id": "…", "hostname": "box-b", "state": "stopped" }
  ]
}

Exception: the OAuth token endpoint (POST /api/v1/oauth/token) does not use this envelope — it returns the token response directly, following the OAuth 2.0 RFC.

Error

{
  "error": {
    "code": "SCREAMING_SNAKE_CASE",
    "message": "Human-readable description"
  }
}

The HTTP status code and error.code together give you everything you need to handle the failure programmatically. The message is for display only and may change between releases — do not parse it.

Error codes

HTTP	error.code	When it occurs
401	UNAUTHORIZED	No valid credentials provided
403	FORBIDDEN	Authenticated but not allowed
403	CSRF_REJECTED	Session-cookie request missing a valid x-csrf-token
400	VALIDATION_FAILED	Request body or query param failed validation
400	BAD_REQUEST	Malformed request
404	NOT_FOUND	Resource not found
404	CONTAINER_NOT_FOUND	Specific container ID not found
404	COMMAND_NOT_FOUND	Specific command job ID not found
501	NOT_IMPLEMENTED	Endpoint exists but feature is not enabled
500	INTERNAL_ERROR	Unexpected server error