REST API

JSON over HTTPS. Bearer-token authenticated. Tenant-scoped per API key.

Authentication

Every request must include an Authorization header with a Bearer token issued in your organization's settings.

Authorization: Bearer rk_<your-key>

Keys are issued by your organization's admin in Settings → API keys. Each key has explicit scopes (e.g. TASKS_READ) and an optional expiry. The plain key is shown once on creation; store it securely.

If a request fails with 401 the key is invalid, revoked, or expired. 403 insufficient_scope means the key lacks the required scope for that endpoint.

Base URL & versioning

https://vesper.rallyve.com/api/v1

All endpoints are versioned. Breaking changes will introduce a new version (v2) without removing the old one.

Pagination

List endpoints support ?limit= (max 200, default 50) and ?cursor=<last_id>. The response includes nextCursor when more results exist.

Endpoints

GET/mescope: any

Returns key + organization metadata. Useful for sanity-checking a key.

GET/tasksscope: TASKS_READ

List tasks. Filters: status, tier, workspace (slug), since (ISO 8601 — only tasks updated after).

POST/tasksscope: TASKS_WRITE

Create a task. Body: { name, type?, tier?, status?, workspace, ownerEmail?, startDate?, endDate?, description? }.

GET/tasks/:idscope: TASKS_READ

Read a single task.

PATCH/tasks/:idscope: TASKS_WRITE

Update name, status, tier, dates, or description.

GET/eventsscope: EVENTS_READ

List event-type tasks. Filters: scheduled=true|false, workspace.

GET/usersscope: USERS_READ

List members of your organization.

GET/comments?taskId=…scope: COMMENTS_READ

List comments on a task.

POST/commentsscope: COMMENTS_WRITE

Add a comment. Body: { taskId, body }.

Examples (curl)

# Sanity check
curl https://vesper.rallyve.com/api/v1/me \
  -H "Authorization: Bearer rk_…"

# List open T1 tasks
curl "https://vesper.rallyve.com/api/v1/tasks?status=PENDING&tier=T1" \
  -H "Authorization: Bearer rk_…"

# Create a task
curl -X POST https://vesper.rallyve.com/api/v1/tasks \
  -H "Authorization: Bearer rk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Investigate latency spike",
    "tier": "T1",
    "workspace": "noc",
    "ownerEmail": "alice@acme.com"
  }'

# Mark a task done
curl -X PATCH https://vesper.rallyve.com/api/v1/tasks/clxyz123… \
  -H "Authorization: Bearer rk_…" \
  -H "Content-Type: application/json" \
  -d '{"status":"DONE"}'

Errors

All errors return JSON with a stable error code and an optional human message.

{
  "error": "insufficient_scope",
  "required": ["TASKS_WRITE"],
  "missing":  ["TASKS_WRITE"]
}

missing_authorization — no Bearer header (401)
invalid_key / invalid_key_format — key not recognized (401)
key_revoked / key_expired — admin revoked or expiry passed (401)
insufficient_scope — key lacks required scope (403)
organization_suspended — org account suspended (403)
not_found — resource doesn't exist or isn't in your org (404)
validation — body failed schema validation (422)

Rate limits

For now, the API is generously rate-limited per key (~10 req/sec). We recommend exponential backoff on 429 responses. Stricter limits may be introduced for free-tier orgs in the future.