Skip to Content
Pocket Notifier

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 APIApp API
ForScripts, CI, serversThe mobile app
StyleREST + JSON, OpenAPIoRPC over /api/rpc
AuthAuthorization: Bearer nt_...better-auth session cookie
ContractpublicContract in src/public.tsappContract 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

MethodPathPurpose
POST/v1/projects/{project}/messagesPublish a message
GET/v1/projects/{project}/messagesList a project's messages
GET/v1/messages/{id}Get one message
GET/v1/messages/{id}/responsesRead replies and acknowledgements
POST/v1/projects/{project}/attachmentsUpload 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) and cursor, and return { items, nextCursor }. Pass nextCursor back as cursor to get the next page. null means 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.

On this page