Response Format

All v2 endpoints return a consistent JSON envelope. This makes parsing predictable — every response has the same top-level structure regardless of success or failure.

Envelope Fields

Field	Type	Description
`timestamp`	string	ISO 8601 timestamp of response generation
`success`	boolean	`true` if the request succeeded, `false` on error
`message`	string	Human-readable status message
`errorCode`	string	Machine-readable error code — empty string `""` on success
`type`	string	Data type name of the object in `data` — empty string `""` on error
`data`	object \| null	The response payload — `null` on error

Success Response

{
  "timestamp": "2026-03-24T12:00:00.000Z",
  "success": true,
  "message": "Chart generated",
  "errorCode": "",
  "type": "ChartSimpleResult",
  "data": {
    "type": "Generator",
    "profile": "6/2",
    "gates": ["20", "34", "10", "57"],
    "channelsShort": ["20-34", "10-57"],
    "centers": ["G", "Sacral", "Spleen", "Throat"]
  }
}

Error Response

{
  "timestamp": "2026-03-24T12:00:01.000Z",
  "success": false,
  "message": "Birthdate must be in YYYY-MM-DD format",
  "errorCode": "INVALID_BIRTHDATE",
  "type": "",
  "data": null
}

Data Types

The type field tells you what shape the data object has:

Type Value	Returned By	Description
`ChartResult`	`/v2/charts`, `/v2/charts/coordinates`	Full chart with all properties (type, profile, channels, centers, strategy, authority, incarnation cross, activations, and more)
`ChartSimpleResult`	`/v2/charts/simple`	Simplified chart (type, profile, gates, channels, centers)

Parsing Guidelines

Check success first — determines whether data is populated or null
Use errorCode for logic — never parse message for error handling. Messages are human-readable and may change without notice.
data is always a single object — v2 chart endpoints return one chart per request, never an array

v1 Response Format

v1 endpoints return the chart data directly as a flat JSON object — no envelope. Field names use snake_case (e.g., channels_short, incarnation_cross). See the migration guide for differences.

Getting Started

Guides

Migration

Envelope Fields

Success Response

Error Response

Data Types

Parsing Guidelines

v1 Response Format

​Envelope Fields

​Success Response

​Error Response

​Data Types

​Parsing Guidelines

​v1 Response Format

Envelope Fields

Success Response

Error Response

Data Types

Parsing Guidelines

v1 Response Format