Spaces:
Sleeping
Sleeping
File size: 7,342 Bytes
24f0bf0 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 | # api-reference
## overview
This is the operational HTTP and WebSocket reference for the running FastAPI app in `backend/app/main.py`.
## base-contract
| item | value |
| --- | --- |
| base-prefix | `/api` |
| swagger-ui | `/swagger` |
| redoc | `/redoc` |
| openapi-json | `/openapi.json` |
| websocket-prefix | `/ws` |
## route-groups
| group | prefix | canonical-purpose |
| --- | --- | --- |
| health | `/api` | liveness/readiness checks |
| episode | `/api/episode` | reset/step/state lifecycle |
| tasks | `/api/tasks` | task catalog and creation |
| agents | `/api/agents` | agent listing/execution/plan/install |
| tools | `/api/tools` | tool registry and tool testing |
| memory | `/api/memory` | store/query/update/clear memory entries |
| settings | `/api/settings` | api-key and model preferences |
| plugins | `/api/plugins` | plugin install/uninstall and tool catalog |
| sites | `/api/sites` | template listing/matching |
| scrape | `/api/scrape` | scrape execution and session result APIs |
| providers | `/api/providers` | provider/model metadata and cost summary |
| websocket | `/ws` | real-time episode stream |
## health-endpoints
| method | path | description |
| --- | --- | --- |
| `GET` | `/api/health` | liveness check |
| `GET` | `/api/ready` | readiness/dependency check |
| `GET` | `/api/ping` | lightweight ping |
## episode-endpoints
| method | path | description |
| --- | --- | --- |
| `POST` | `/api/episode/reset` | create episode and return initial observation |
| `POST` | `/api/episode/step` | apply one action and return transition |
| `GET` | `/api/episode/state/{episode_id}` | current episode snapshot |
| `GET` | `/api/episode/` | list active/recent episodes |
| `DELETE` | `/api/episode/{episode_id}` | delete episode state |
## task-endpoints
| method | path | description |
| --- | --- | --- |
| `GET` | `/api/tasks/` | list available tasks |
| `GET` | `/api/tasks/{task_id}` | fetch one task |
| `POST` | `/api/tasks/` | create dynamic task |
| `GET` | `/api/tasks/types/` | list task-type catalog |
## agent-endpoints
| method | path | description |
| --- | --- | --- |
| `GET` | `/api/agents/list` | list available agents |
| `POST` | `/api/agents/run` | run one agent request |
| `POST` | `/api/agents/plan` | request generated plan |
| `GET` | `/api/agents/state/{agent_id}` | fetch one agent state |
| `GET` | `/api/agents/types/` | list agent types |
| `GET` | `/api/agents/catalog` | full agent catalog |
| `GET` | `/api/agents/installed` | installed agents |
| `POST` | `/api/agents/install` | install agent |
| `POST` | `/api/agents/uninstall` | uninstall agent |
| `POST` | `/api/agents/message` | send message to running agent |
## tool-and-plugin-endpoints
### tools
| method | path | description |
| --- | --- | --- |
| `GET` | `/api/tools/registry` | list tools in registry |
| `GET` | `/api/tools/registry/{tool_name}` | tool metadata/details |
| `POST` | `/api/tools/test` | execute tool test run |
| `GET` | `/api/tools/categories` | tool category summary |
### plugins
| method | path | description |
| --- | --- | --- |
| `GET` | `/api/plugins` | list plugins (alias without trailing slash also available) |
| `GET` | `/api/plugins/installed` | list installed plugins |
| `GET` | `/api/plugins/categories` | category summary |
| `GET` | `/api/plugins/tools` | list plugin tools |
| `GET` | `/api/plugins/tools/{tool_name:path}` | tool details |
| `GET` | `/api/plugins/registry` | registry endpoint |
| `GET` | `/api/plugins/summary` | compact plugin summary |
| `GET` | `/api/plugins/{plugin_id}` | single plugin by id |
| `POST` | `/api/plugins/install` | install plugin |
| `POST` | `/api/plugins/uninstall` | uninstall plugin |
## memory-endpoints
| method | path | description |
| --- | --- | --- |
| `POST` | `/api/memory/store` | create memory entry |
| `POST` | `/api/memory/query` | semantic/filter query |
| `GET` | `/api/memory/{entry_id}` | read one entry |
| `PUT` | `/api/memory/{entry_id}` | update one entry |
| `DELETE` | `/api/memory/{entry_id}` | delete one entry |
| `GET` | `/api/memory/stats/overview` | memory layer stats |
| `DELETE` | `/api/memory/clear/{memory_type}` | clear one layer |
| `POST` | `/api/memory/consolidate` | memory consolidation |
## settings-provider-and-sites-endpoints
### settings
| method | path | description |
| --- | --- | --- |
| `GET` | `/api/settings` | get settings (alias with trailing slash also available) |
| `POST` | `/api/settings/api-key` | update runtime api-key |
| `POST` | `/api/settings/model` | set active model |
| `GET` | `/api/settings/api-key/required` | whether key is required |
### providers
| method | path | description |
| --- | --- | --- |
| `GET` | `/api/providers` | list providers (alias with trailing slash also available) |
| `GET` | `/api/providers/{provider_name}` | provider details |
| `GET` | `/api/providers/models/all` | flattened model list |
| `GET` | `/api/providers/costs/summary` | token/cost summary |
| `POST` | `/api/providers/costs/reset` | reset provider cost tracking |
### sites
| method | path | description |
| --- | --- | --- |
| `GET` | `/api/sites` | list built-in templates |
| `GET` | `/api/sites/{site_id}` | template detail |
| `POST` | `/api/sites/match` | infer matching template |
## scrape-endpoints
| method | path | description |
| --- | --- | --- |
| `POST` | `/api/scrape/stream` | streaming scrape run (`text/event-stream`) |
| `POST` | `/api/scrape/` | synchronous scrape request |
| `GET` | `/api/scrape/sessions` | list scrape sessions |
| `GET` | `/api/scrape/{session_id}/status` | status for one session |
| `GET` | `/api/scrape/{session_id}/result` | final result payload |
| `GET` | `/api/scrape/{session_id}/sandbox/files` | list sandbox artifacts |
| `GET` | `/api/scrape/{session_id}/sandbox/files/{file_name}` | fetch one artifact |
| `DELETE` | `/api/scrape/{session_id}` | cancel active session |
| `DELETE` | `/api/scrape/{session_id}/cleanup` | cleanup artifacts/session cache |
## websocket-endpoint
| protocol | path | description |
| --- | --- | --- |
| `ws` | `/ws/episode/{episode_id}` | real-time episode event stream |
## scrape-stream-event-shape
| field | type | notes |
| --- | --- | --- |
| `type` | string | `init`, `step`, `url_start`, `url_complete`, `complete`, `error` |
| `data` | object | event payload |
| `data.action` | string | step action (`tool_call`, `agent_decision`, etc.) |
| `data.status` | string | runtime status |
| `data.extracted_data` | object/null | structured output for the step |
## request-flow
```mermaid
sequenceDiagram
participant C as client
participant A as fastapi-app
participant R as route-handler
participant E as env-agent-runtime
C->>A: HTTP/WS request
A->>R: route dispatch
R->>E: execute action/query
E-->>R: structured result
R-->>C: JSON response or stream event
```
## error-model
| status-code | meaning |
| --- | --- |
| `400` | invalid request payload or unsupported operation |
| `404` | resource not found (`episode_id`, `session_id`, `entry_id`) |
| `422` | validation error (FastAPI schema mismatch) |
| `500` | uncaught server/runtime error |
## document-metadata
| key | value |
| --- | --- |
| document | `api-reference.md` |
| source | `backend/app/main.py` route graph |
| status | active |
|