DEVELOPER PLATFORM / API V1
Your tools.
Connected to your workspace.
Query status, inspect modules and run permission-checked bot actions. Keep credentials out of your frontend.
Start with a read key
Create a key in your workspace, then send it in the Authorization header. Requests use HTTPS on your public domain.
curl 'https://404bot.de/api/v1/bots' \ -H 'Authorization: Bearer YOUR_API_KEY'
Keys inherit their creator's current permissions. Disabled accounts, removed access, expiry or revocation stop access immediately.
Predictable operations
- Authentication
- Bearer API key
- Pagination
- limit: 1-100, offset: 0+
- Key limit
- 60 requests / minute
- Writes
- Control scope + UUID
- Replay retention
- 24 hours
An additional global IP limit applies. Read-only diagnostic actions can use read keys; write actions require control.
Endpoint reference
| Method | Endpoint | Purpose / scope |
|---|---|---|
| GET | /api/v1/status | Service statusreadRelease and key workspace. |
| GET | /api/v1/workspace | Workspace summaryreadWorkspace identity and creator identity. |
| GET | /api/v1/bots | List botsreadPermission-filtered bot metadata. No tokens or configuration secrets. |
| GET | /api/v1/bots/{id} | Inspect a botreadWorker status and connected guilds. |
| GET | /api/v1/bots/{id}/modules | List bot modulesreadModule keys and enabled flags only. |
| GET | /api/v1/bots/{id}/logs | Read worker logsreadRecent lines with credential redaction. |
| POST | /api/v1/bots/{id}/actions | Run a bot actioncontrol for writesSupported console actions, checked against the creator permissions. |
| PATCH | /api/v1/bots/{id}/modules/{module} | Toggle a modulecontrolChange enabled state without overwriting existing module configuration. |
| GET | /api/v1/servers | List game serversreadPermission-filtered metadata; add live=1 for external connection probes. |
| POST | /api/v1/servers/{id}/restart | Restart game servercontrolRequires servers.control, confirmed=true and an idempotency UUID. |
| GET | /api/v1/events | List eventsreadPermission-filtered event metadata and registration counts. |
| GET | /api/v1/events/{id}/registrations | Event registrationsread + events.reviewIncludes participant data; only users with event-review rights can read it. |
| GET | /api/v1/activity | Workspace activityread + activity.viewRecent action summaries, without raw audit details. |
A deliberate write
Restart requires control scope, bot restart permission and confirmation. Use a fresh UUID for each new operation; keep it for retries.
curl -X POST 'https://404bot.de/api/v1/bots/1/actions' \
-H 'Authorization: Bearer YOUR_CONTROL_KEY' \
-H 'Idempotency-Key: 76f1d9c5-f7fb-4a16-938c-a794a9e1892e' \
-H 'Content-Type: application/json' \
-d '{"command":"restart","confirmed":true}'A repeated UUID with the same body replays the stored result. Changed payloads are rejected. In-progress or unknown outcomes return 409; check the worker before trying a new action.
Read-only API explorer
Test a read request on this panel. The key stays in this page's memory and is sent only to this same origin. Nothing is saved to browser storage.
No request sent.
Errors & compatibility
400 invalid input. 401 key unavailable. 403 permissions or scope. 404 missing resource. 409 confirmation, replay conflict or busy action. 429 rate limit. 502 external service failure.
Legacy API keys remain recognized. Existing endpoints remain, but sensitive data is now allowlisted and permissions are checked against the key creator. Game-server live probes require ?live=1. API clients must handle error responses before retrying.