Admin Operations

Admin endpoints are destructive. Restrict access in production.

When authentication is enabled, all admin endpoints require a valid credential and one of the configured admin_roles. Add -H "Authorization: Bearer <token>" or -u user:pass (direct mode) to the curl examples below.

Delete One Notification

DELETE /api/v1/admin/notification/{notification_id}

notification_id format:

• <stream>@<sequence> (canonical)
• <event_type>@<sequence> (alias; resolved through configured schema topic.base)

How notification_id maps to your schema

Delete IDs use the stream key plus backend sequence number.

If your schema contains:

notification_schema:
  mars:
    topic:
      base: "mars"
  dissemination:
    topic:
      base: "diss"
  test_polygon:
    topic:
      base: "polygon"

Then valid delete IDs include:

• mars@42 (event type alias and stream key are same)
• dissemination@42 (alias form, resolved to stream key diss)
• diss@42 (canonical stream key form)
• test_polygon@306 (alias form, resolved to stream key polygon)
• polygon@306 (canonical stream key form)

Example: replay ID then delete

Replay returns CloudEvent IDs like mars@1:

curl -N -X POST "http://127.0.0.1:8000/api/v1/replay" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "mars",
    "identifier": {
      "class": "od",
      "expver": "0001",
      "domain": "g",
      "date": "20250706",
      "time": "1200",
      "stream": "enfo",
      "step": "1"
    },
    "from_id": "1"
  }'

If one replayed event has "id":"mars@1", delete it with:

curl -X DELETE "http://127.0.0.1:8000/api/v1/admin/notification/mars@1"

Response behavior

• 200: notification deleted.
• 404: stream/sequence pair not found.
• 400: invalid ID format (<name>@<positive-integer> required).

The response body has the shape:

{
  "success": true,
  "message": "Notification deleted",
  "notification_id": "mars@42",
  "request_id": "<uuid>"
}

Failure responses (404, 400) keep the same fields with success: false and a descriptive message.

Invalid examples:

• mars (missing @sequence)
• mars@0 (sequence must be > 0)
• mars@abc (sequence must be an integer)

Wipe Endpoints

• DELETE /api/v1/admin/wipe/stream
• DELETE /api/v1/admin/wipe/all

These endpoints remove many messages at once and should be used with extreme caution.

Wipe One Stream

DELETE /api/v1/admin/wipe/stream

Request body:

{
  "stream_name": "mars"
}

stream_name accepts the event type as configured in the notification schema or the backend stream name, case-insensitively: mars and MARS wipe the same stream.

Example:

curl -X DELETE "http://127.0.0.1:8000/api/v1/admin/wipe/stream" \
  -H "Content-Type: application/json" \
  -d '{"stream_name":"mars"}'

What it does:

• Removes all stored messages for the selected stream.
• Keeps the stream definition/configuration in place.
• New notifications can still be written to that stream immediately after wipe.

When no stream matches the name, the response is 404 and the message lists the configured event types, so a typo is distinguishable from a backend failure (500).

When to use:

• You want to reset one event family (mars, diss, polygon) without affecting others.

Wipe All Streams

DELETE /api/v1/admin/wipe/all

Example:

curl -X DELETE "http://127.0.0.1:8000/api/v1/admin/wipe/all"

What it does:

• Removes all stored messages from all streams managed by the backend.
• Leaves service configuration intact, but data history is gone.

When to use:

• Local/dev reset before a fresh test run.
• Operational emergency cleanup where full history removal is intended.

Which Admin Operation Should I Use?

• Delete one notification (/admin/notification/{id}):
  • Use when you know the exact sequence to remove.
• Wipe one stream (/admin/wipe/stream):
  • Use when one stream is polluted and others must remain untouched.
• Wipe all (/admin/wipe/all):
  • Use only when complete history reset is intended.

Wipe Response Shape

Both wipe endpoints return the same field set: success, message, request_id. The message value differs:

DELETE /api/v1/admin/wipe/stream:

{
  "success": true,
  "message": "Successfully wiped stream: MARS",
  "request_id": "<uuid>"
}

DELETE /api/v1/admin/wipe/all:

{
  "success": true,
  "message": "Successfully wiped all data",
  "request_id": "<uuid>"
}

Failure responses keep the same fields with success: false and a descriptive message.