mirror of
https://github.com/Colton-z/AstraBox.git
synced 2026-09-28 06:02:56 +08:00
Colton Qi
f8db994652
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.
100 lines
3.0 KiB
Markdown
100 lines
3.0 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"code": "OK",
|
|
"message": "success",
|
|
"data": {
|
|
"session_id": "21e061ee-c00b-48cb-a702-fc8f410792f7"
|
|
}
|
|
}
|
|
```
|
|
|
|
<Note>Streaming, file-download, MCP, redirect, and `204 No Content` endpoints
|
|
use the response type declared for that operation instead of the JSON success
|
|
envelope.</Note>
|
|
|
|
## 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](api-pagination.md) for request parameters and traversal examples.
|
|
|
|
## Error envelope
|
|
|
|
Error responses use this envelope:
|
|
|
|
```json
|
|
{
|
|
"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](api-errors.md) 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](overview.md) — how AstraBox fits together.
|