mirror of https://github.com/Colton-z/AstraBox.git synced 2026-09-28 06:02:56 +08:00

Files

T

The open-source, self-hosted alternative to Claude Managed Agents: run
Claude Code, Codex, Hermes, DeepSeek Harness and Pi as managed Agents on
your own infrastructure, with conversations that start and resume in
seconds.

2026-09-22 13:24:05 -07:00

3.0 KiB

Raw Permalink Blame History

Common data structures

Reuse the response envelopes and identifiers shared across the AstraBox API.

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.

3.0 KiB Raw Permalink Blame History