API overview
The two APIs, how to authenticate, and the conventions they share.
notifier has two APIs, both defined as oRPC contracts in packages/contract Decided.
| Public API | App API | |
|---|---|---|
| For | Scripts, CI, servers | The mobile app |
| Style | REST + JSON, OpenAPI | oRPC over /api/rpc |
| Auth | Authorization: Bearer nt_... | better-auth session cookie |
| Contract | publicContract in src/public.ts | appContract in src/app.ts |
| Base path | /api/v1 | /api/rpc |
The server lives under /api on https://notifier.bartuozel.com; the docs site is the root. The examples set NOTIFIER_URL to that API base, so paths read /v1/.... The interactive API reference is at /api/v1/docs and the OpenAPI document at /api/v1/spec.json.
Authentication
export NOTIFIER_URL=https://notifier.bartuozel.com/api
export NOTIFIER_TOKEN=nt_...
curl "$NOTIFIER_URL/v1/projects/ci/messages" \
-H "Authorization: Bearer $NOTIFIER_TOKEN"Create tokens in the dashboard under Settings → Access tokens. See Access tokens for scopes.
Endpoints
| Method | Path | Purpose |
|---|---|---|
POST | /v1/projects/{project}/messages | Publish a message |
GET | /v1/projects/{project}/messages | List a project's messages |
GET | /v1/messages/{id} | Get one message |
GET | /v1/messages/{id}/responses | Read replies and acknowledgements |
POST | /v1/projects/{project}/attachments | Upload an attachment |
The OpenAPI document is generated from publicContract, so it always matches the code.
Conventions
- JSON request and response bodies. The exception is attachment upload, which uses
multipart/form-data. - Timestamps are ISO-8601 strings in UTC:
2026-11-20T12:00:00.000Z. - IDs have a type prefix:
prj_,msg_,att_,rsp_,tok_,inv_,dev_. See Data model. - Pagination. List endpoints take
limit(1–100, default 50) andcursor, and return{ items, nextCursor }. PassnextCursorback ascursorto get the next page.nullmeans there are no more items. Results are newest first. - Errors follow one shape, described in Errors.
- Versioning. Breaking changes get a new prefix (
/v2). Adding optional fields is not a breaking change, so clients should ignore fields they do not know.