PulseRoster API

Authentication

Send your key as a bearer token. The X-API-Key header works too, for HTTP clients that make setting Authorization awkward.

curl https://roster.mypulsetech.com/api/v1/whoami \
  -H "Authorization: Bearer prk_a1b2c3d4_<secret>"

GET /api/v1/whoami is the first call to make: it confirms the key is live and shows which community and scopes it carries.

Responses

Every response uses the same envelope, success or failure, so a client can branch on success.

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "request_id": "a1b2c3d4",
    "pagination": { "page": 1, "limit": 25, "total": 84, "total_pages": 4, "has_more": true }
  }
}

{
  "success": false,
  "error": { "code": "insufficient_scope", "message": "This key lacks the required scope: roster:write" },
  "meta": { "request_id": "e5f6a7b8" }
}

meta.request_id is also returned as the X-Request-Id header and written to our logs. Quote it in a support message and we can find the exact request.

Rate limits

120 requests per minute and 25,000 per day, per key. A key can be given a lower per-minute limit in settings.

• X-RateLimit-Limit: the ceiling for the window closest to exhaustion.
• X-RateLimit-Remaining: requests left. Present on successes too, so you can back off before you are throttled.
• X-RateLimit-Reset: unix seconds when the window rolls over.
• Retry-After: seconds to wait. Sent only with a 429.

Query conventions

Every list endpoint supports the same parameters. Which fields are filterable, sortable or searchable is listed per resource below.

• ?page=2&limit=50: pagination. Limit caps at 100.
• ?sort=-createdAt: sort, - for descending.
• ?q=smith: case-insensitive search across the resource's search fields.
• ?status=ACTIVE&status=ON_LOA: repeat an enum filter to mean "either".
• ?createdAt.after=2026-01-01T00:00:00Z: date range on any date-time field. .before too.
• ?include=member,rank: expand related records.

Scopes

A key carries an explicit scope list. A :write scope implies its :read counterpart. You can only grant scopes you hold the matching staff permission for, so a key is never more powerful than the person who made it.

Errors

Endpoints

22 resources. All paths are relative to https://roster.mypulsetech.com.