Generic Data Structures

AstraBox API groups reuse the following cross-resource structures. Each AstraBox instance publishes resource-specific request and response structures at /docs and /openapi.json.

Success envelope

AstraBox REST resource handlers return the operation's result in data.

Field	Type	Description
code	string	OK for a successful request
message	string	success for a successful request
data	any	The operation's response value

Example:

{
  "code": "OK",
  "message": "success",
  "data": {
    "session_id": "21e061ee-c00b-48cb-a702-fc8f410792f7"
  }
}

Streaming, file-download, MCP, redirect, and 204 No Content endpoints use the response type declared for that operation instead of the JSON success envelope.

Paginated list

The paginated Session list returns its cursor page inside the standard success envelope:

Field	Type	Description
data.sessions	array	Session objects on the current page
data.has_more	boolean	Whether more Sessions are available
data.next_cursor	string | null	Opaque cursor for the next page, or null at the end

Pass data.next_cursor back as the cursor query parameter. See Pagination for request parameters and traversal examples.

Error envelope

Error responses use this envelope:

{
  "code": "INVALID_REQUEST",
  "message": "permission_mode is required",
  "data": null,
  "error": {
    "code": "INVALID_REQUEST",
    "status_code": 400,
    "category": "request",
    "retryable": false,
    "owner": "client",
    "user_message": "permission_mode is required"
  }
}

Field	Type	Description
code	string	Stable error code for programmatic handling
message	string	Message safe to show to the caller
data	any | null	Error-specific structured data, when available
error	object	Error status, category, retryability, owner, caller-safe message, and optional diagnostics

See Errors for every envelope field and handling guidance.

Timestamp

Platform-generated timestamps are ISO 8601 / RFC 3339 strings in UTC, for example "2026-08-24T19:26:39.616690+00:00". Some fields are nullable; each resource schema calls that out explicitly.

Identifiers

AstraBox identifiers are opaque strings. Resources do not share one public ID prefix convention.

Rule	Description
Type	JSON string
Source	Read the ID from the create, list, or detail response
Use	Pass the complete value unchanged in path parameters and request fields
Meaning	Determine the resource type from its field and endpoint, not from the ID text
Storage	Store enough characters for the returned value; do not assume a UUID or fixed length

Next steps

• Overview — how AstraBox fits together.