> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ameo.agiwithai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Worker API

> REST endpoints for the AMEO Python worker.

Base URL: `http://localhost:8000` (local) or `https://agentic-micro-economy-os.onrender.com` (Render).

The web console may also read Mantle RPC directly via wagmi for on-chain events.

## Authentication

MVP assumes a trusted operator network. Do not expose unauthenticated `/api/start` or `/run-cycle` on the public internet without rate limits and auth.

## Endpoints

### `GET /health`

Liveness probe.

```json theme={null}
{ "status": "ok" }
```

### `GET /api/status`

Agent runner state, last cycle metadata, observation snapshot.

### `GET /api/history`

Recent runs / decisions from SQLite memory.

### `GET /api/policy`

Default guardrail parameters (max slippage, caps, whitelist).

### `GET /api/public-config`

Non-secret operational metadata (chain id, contract address, worker mode).

### `GET /api/eval-report`

Parsed `eval_report.json` (decision-quality metrics).

### `GET /api/cycles`

List recorded cognition cycles from JSONL event store.

Query: `limit`, `offset`

### `GET /api/cycles/{cycle_id}`

Full replay payload for one cycle (nine-node reconstruction).

### `GET /api/decisions`

On-chain `[DecisionLogged](/glossary#decisionlogged-event)` events via Mantle client.

### `GET /api/events/tail`

Server-Sent Events stream of append-only JSONL worker events.

### `GET /api/llm-chain`

LLM provider fallback chain status.

### `POST /api/start` · `POST /api/stop`

Start/stop scheduled agent runner.

### `POST /run-cycle`

Trigger a single observe-plan-act-log cycle.

```json theme={null}
{
  "correlation_id": "uuid",
  "outcome": "executed|no_op|policy_rejected|error",
  "tx_hash": "0x..."
}
```

## On-chain events

Read `DecisionLogged` from `AGENT_IDENTITY_ADDRESS`:

```solidity theme={null}
event DecisionLogged(
    uint256 indexed agentId,
    bytes32 rationaleHash,
    int256 pnl1e18,
    string actionType,
    string metadataUri,
    string dataHash,
    address operator
);
```

## Errors

| HTTP | Meaning                    |
| ---- | -------------------------- |
| 403  | Policy rejected plan       |
| 404  | Cycle not found            |
| 503  | RPC or adapter unavailable |
| 429  | Rate limited               |

## Webhooks

None in MVP.

See [Contracts API](/api/contracts) for on-chain interface details.