Response Envelopes
Use this page to understand the response shapes clients should preserve rather than flatten away.
Who This Is For
- SDK authors and maintainers
- developers implementing direct HTTP clients
- AI agents reasoning about runtime verification and download behavior
When To Use This
Read this page whenever envelope shape matters more than route-by-route walkthroughs.
How It Works
Management success
Management success responses use:
json
{
"data": {},
"meta": {}
}Runtime success
Runtime success responses use:
json
{
"data": {},
"signature": {},
"meta": {}
}The signature covers the JSON bytes of data.
Error responses
Errors use:
json
{
"error": {},
"meta": {}
}No-content responses
Some routes intentionally return 204 No Content with no body.
Export downloads
GET /api/v1/reports/exports/{id}/download is format-dependent and may return:
- JSON
- CSV
Do not assume every successful response is a JSON envelope.
Example
Management:
json
{
"data": {
"id": "prod_123"
},
"meta": {
"request_id": "req_123"
}
}Runtime:
json
{
"data": {
"license_id": "lic_123",
"status": "active"
},
"signature": {
"kid": "sig_123"
},
"meta": {
"request_id": "req_123"
}
}Common Mistakes
- flattening runtime envelopes and losing
signature - assuming export downloads always return JSON
- inventing a body for
204 No Contentroutes