AstraBox/docs/api.md

API Overview

Connect to a deployed AstraBox API and discover its exact current surface.

The AstraBox API provides full management capabilities for self-hosted cloud Agents, covering Agent creation, Environment configuration, Session lifecycle, event streaming, files, Deployments, credentials, and more. REST endpoints use JSON for requests and responses; streaming endpoints use Server-Sent Events.

Every AstraBox instance publishes interactive API documentation at /docs; the OpenAPI document at /openapi.json describes the exact API surface of the deployed release.

Gateway URL

Environment	URL
Self-hosted production	https://astrabox.example.com/api/v1
Local development	http://127.0.0.1:8088/api/v1

Replace astrabox.example.com with the public origin of your deployment.

Versioning

The API is currently at version v1. Endpoints use the /api/v1 prefix; no additional version header is required. Health, readiness, metrics, and generated API documentation use top-level paths.

Available APIs

Resource	Description	Base path
Agents	Create, read, update, delete, and authorize Agents	/agents
Assistants	Manage Assistants and their persistent workspaces	/assistants
Environments	Manage the infrastructure available to Agents	/admin/environments
Sessions	Read Session state, submit turns, stream events, and manage lifecycle	/sessions
Files	List, upload, move, download, and delete files in a Session workspace	/sessions/{session_id}/files
Extensions	Assign remote MCP servers and Skills to an Agent	/agents/{agent_id}/extensions
Remote MCP servers	Manage administrator-provided remote MCP connections	/admin/mcp-servers
Vaults	Store Credentials and assign Vaults to Agents or Assistants	/admin/vaults
Deployments	Schedule an Agent, expose a webhook, or connect a messaging product	/admin/agents/{agent_id}/deployments
MCP	Expose accessible Agents to an MCP client	/mcp
Authentication	Browser login, callback, logout, and current-login state	/auth
Administration	Inspect sandboxes, Sessions, operations, and instance configuration	/admin

A Session is created through an Agent or Assistant conversation endpoint; there is no independent POST /sessions payload.

Request size limits

AstraBox does not impose one global JSON request-body limit across every route. The reverse proxy may set a deployment-wide limit, and individual endpoints enforce limits required by their resource. File uploads are streamed. A single Files API download is limited to 64 MiB so one response cannot consume unbounded API-process memory.

When operating behind a proxy, configure its request, response, and streaming timeouts for the largest operation the deployment permits. Return 413 from the proxy when a request is too large.

Required headers

Team deployments require a valid browser cookie or bearer token on protected routes. JSON requests should include Content-Type:

Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

The Authorization header is omitted in loopback-only local identity mode. Conversation creation also accepts an optional Idempotency-Key header. Reuse the same key only for the same user and Agent or Assistant.

Release compatibility

1. The API surface belongs to the installed AstraBox release.
2. Pin the AstraBox release used in production.
3. During an upgrade, review that release's /openapi.json document and regenerate typed clients from it.

Quick connectivity check

# List Agents visible to the current identity
curl --fail --silent --show-error \
  "$SERVICE_URL/api/v1/agents" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Successful response:

{
  "code": "OK",
  "message": "success",
  "data": []
}

Rate Limiting

The API application layer has no active rate limiting by default. A deployment can install admission policy and enforce traffic limits at its proxy or gateway. Those controls may return 429, while unavailable infrastructure may return 503.

Clients should limit concurrency and use bounded exponential backoff for 429 and retryable 5xx responses. When an admission denial includes data.retry_after_seconds, wait at least that long before retrying.

Next steps

• Authentication — authenticate API requests.
• Errors — error codes and troubleshooting.
• Pagination — pagination for list endpoints.