HTTP API
Herald exposes HTTP endpoints for managing streams, members, events, and presence. Authenticate with your API key and secret using HTTP Basic auth.
Base URL
https://herald.skeptik.io/v1
Streams
| Method | Endpoint | Description |
|---|
POST | /v1/streams | Create a stream |
GET | /v1/streams | List streams |
GET | /v1/streams/:id | Get stream details |
PATCH | /v1/streams/:id | Update stream metadata |
DELETE | /v1/streams/:id | Delete a stream |
Members
| Method | Endpoint | Description |
|---|
POST | /v1/streams/:id/members | Add a member |
GET | /v1/streams/:id/members | List members |
PATCH | /v1/streams/:id/members/:user_id | Update member role |
DELETE | /v1/streams/:id/members/:user_id | Remove a member |
Events
| Method | Endpoint | Description |
|---|
POST | /v1/streams/:id/events | Inject an event (server-side publish) |
GET | /v1/streams/:id/events | Query events (before, after, limit) |
PATCH | /v1/events/:id | Edit event body |
DELETE | /v1/events/:id | Delete an event |
Reactions
| Method | Endpoint | Description |
|---|
POST | /v1/events/:id/reactions | Add a reaction (32-byte max, 10 per event) |
DELETE | /v1/events/:id/reactions/:key | Remove a reaction |
Presence
| Method | Endpoint | Description |
|---|
GET | /v1/presence | Batch query (?user_ids=a,b,c) |
GET | /v1/presence/:user_id | Single user presence |
GET | /v1/streams/:id/presence | All member presence in a stream |
GET | /v1/streams/:id/cursors | All cursors in a stream |
Other endpoints
| Method | Endpoint | Description |
|---|
POST | /v1/streams/:id/triggers | Server-side ephemeral event |
POST | /v1/blocks | Block a user (directional) |
DELETE | /v1/blocks/:user_id | Unblock a user |
GET | /v1/stats | Account statistics |
Self-service endpoints
These endpoints let you manage your own credentials and inspect usage without admin access.
| Method | Endpoint | Description |
|---|
GET | /self/connections | List active connections |
GET | /self/events | Event log |
GET | /self/errors | Error log |
POST | /self/rotate-secret | Rotate API secret |
POST | /self/tokens | Generate a connection token |
Pagination
List endpoints support limit and offset query parameters. Default limit is 50, maximum is 100. Event queries also support before and after for sequence-based pagination.