57 lines
1.5 KiB
Plaintext
57 lines
1.5 KiB
Plaintext
---
|
|
id: api-overview
|
|
title: API Overview
|
|
slug: /platform/api/overview
|
|
sidebar_position: 1
|
|
---
|
|
|
|
`blackroad-os-api` is the HTTP surface that external consumers, Prism Console, and automation call. It wraps Operator runtime data in a consistent envelope.
|
|
|
|
## Envelope
|
|
Every response returns:
|
|
|
|
```json
|
|
{
|
|
"ok": true,
|
|
"data": {"..."}
|
|
}
|
|
```
|
|
|
|
When `ok` is `false`, expect an `error` object with a `code` and `message` instead of `data`.
|
|
|
|
## Endpoints
|
|
- `GET /api/v1/health` — liveness and readiness.
|
|
- `GET /api/v1/system/overview` — summary of system health, agents, and version info.
|
|
- `GET /api/v1/agents` — list registered agents.
|
|
- `GET /api/v1/agents/:id` — inspect a specific agent, including state and last-seen metadata.
|
|
- `GET /api/v1/finance/snapshot` — wallet balances, ROI snapshots, and agent cost rollups (where implemented).
|
|
- `GET /api/v1/events` — paginated DomainEvents from the Operator runtime.
|
|
- `GET /api/v1/roadchain/blocks` — grouped RoadChain blocks for audit references.
|
|
|
|
### Example shapes (pseudocode)
|
|
- **System overview**
|
|
```json
|
|
{
|
|
"ok": true,
|
|
"data": {
|
|
"uptimeSeconds": 1234,
|
|
"agents": {"total": 3, "healthy": 3},
|
|
"jobs": {"queued": 2, "running": 1}
|
|
}
|
|
}
|
|
```
|
|
- **Agent detail**
|
|
```json
|
|
{
|
|
"ok": true,
|
|
"data": {
|
|
"id": "atlas",
|
|
"psShaInfinity": "ps-sha∞-...",
|
|
"state": "ready",
|
|
"lastJob": {"id": "job-123", "status": "succeeded"}
|
|
}
|
|
}
|
|
```
|
|
|
|
Keep endpoints thin and stable: Operator is where jobs run; the API is the consumable contract for Prism, web, and partners.
|