Skip to content

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:

AreaWhat is there
Server, Projectsversion, settings, project list
Eventslist, read, pin, delete events of every type
SMTP, Attachmentsemail testing API, attachment download
Sentryerrors, traces, logs, metrics, counts, clear
Mocksmock server rules, OpenAPI import
Profiler, Xdebug, Xdebug tracesprofiles, the Xdebug proxy, traces
Auth, MetricsSSO login, Prometheus
Ingestionroutes 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? ​

bash
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 ​

bash
# 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 ​

bash
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 ​

bash
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.