API reference
Everything the UI does goes through an HTTP API on port 8000. Your tests and scripts can use the same API, e.g. to wait for an email or to clear events between tests.
The full spec
The whole API is described in one OpenAPI 3.1 file: api/openapi.yaml in the server repository. Open it in any OpenAPI viewer (Swagger UI, Redoc, your IDE) or generate a client from it.
It covers every route of the server, grouped by area:
| Area | What is there |
|---|---|
| Server, Projects | version, settings, project list |
| Events | list, read, pin, delete events of every type |
| SMTP, Attachments | email testing API, attachment download |
| Sentry | errors, traces, logs, metrics, counts, clear |
| Mocks | mock server rules, OpenAPI import |
| Profiler, Xdebug, Xdebug traces | profiles, the Xdebug proxy, traces |
| Auth, Metrics | SSO login, Prometheus |
| Ingestion | routes the SDKs send to (marked x-ingestion: true) |
A server test compares the spec with the routes in the code, so a new route cannot ship without its entry.
Calls for tests
The ones you need most in a test suite or CI job. Examples use http://127.0.0.1:8000.
Is the server up?
curl http://127.0.0.1:8000/api/version
# {"version":"2.11.0"}No login needed, also with SSO on. Use it as a health check.
Start from a clean state
# every event
curl -X DELETE http://127.0.0.1:8000/api/events
# only emails
curl -X DELETE http://127.0.0.1:8000/api/events \
-H 'Content-Type: application/json' -d '{"type": "smtp"}'It deletes events. Sentry logs, metrics and trace spans without an event card stay: clear them with DELETE /api/sentry/all (see Sentry → Clearing data).
The JSON body narrows what is deleted: type, project, uuids (a list of event IDs), keep_pinned: true. Since server 2.11.0, a body that is not valid JSON, or a field of the wrong type, gets 400 and deletes nothing. In 2.10.0 and older the same mistake deletes every event: e.g. {"type": smtp} (no quotes) clears all types.
Wait for an email
curl -G http://127.0.0.1:8000/api/smtp/messages/wait \
--data-urlencode 'subject=Welcome' \
--data-urlencode 'to=user@example.com' \
--data-urlencode 'timeout=10s'It answers 200 with the message as soon as one matches, or 408 when the time is up (at most 60s). More filters and calls: SMTP → Testing API.
List events of one type
curl 'http://127.0.0.1:8000/api/events?type=sentry'
# {"data": [{"uuid": "…", "type": "sentry", "project": "default", "payload": {…}, …}], "meta": {…}}Types: sentry, smtp, monolog, var-dump, ray, inspector, profiler, http-dump, sms, xdebug-trace.
With SSO on
When SSO is on, the UI's API needs the header X-Auth-Token: <token>. See SSO → Calling the API from Scripts. In CI you usually run Buggregator without SSO, so no token is needed.