Build on Nyblit

Quickstart

1. In Nyblit, open Settings → API Access and create a token. Pick only the scopes you need. Copy it — it is shown once. Get a token
2. Check it works:

curl https://api.nyblit.app/v1/me \
  -H "Authorization: Bearer nyb_pat_…"

3. List what is on your Today tab (Disposition key in_progress):

curl "https://api.nyblit.app/v1/tasks?disposition=in_progress&limit=20" \
  -H "Authorization: Bearer nyb_pat_…"

4. Add a task to Today (needs the tasks:write scope):

curl https://api.nyblit.app/v1/tasks \
  -H "Authorization: Bearer nyb_pat_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1e9a52-3f0b-4d1e-9b8a-2f6d5c4e3a10" \
  -d '{"title": "Call the bank", "disposition": "in_progress"}'

Tab labels are customisable, so the API always uses the fixed Disposition keys: not_started, in_progress, waiting, on_hold, done.

Authentication and scopes

Send your token in the Authorization header on every request. Tokens in the URL are rejected, because URLs end up in logs. Treat a token like a password: anyone holding it can act as you within its scopes.

• Tokens always expire. You choose how long when you create one.
• Revoke a token at any time in Settings → API Access; it stops working immediately.
• Tokens start with nyb_pat_, so secret scanners can spot leaked ones.
• A token can do what you can do in Nyblit, to your own data. It can't change account security settings or create other tokens.
• GET /me works with any token and needs no scope. Use it to check a token.

During the beta you can read your tasks (with their steps), projects, workflows, statuses and dispositions, and create, change, complete, archive and delete tasks. Writes for steps, projects and workflows, and webhooks, follow.

Changing tasks

Changes made through the API follow the same rules as the app and sync to every device the account uses.

• Setting a status_id also sets the task's Workflow and Disposition. Changing workflow_id moves the task to that Workflow's first Status for its Disposition. Changing disposition on its own clears the Status.
• on_hold_until only applies in Later (on_hold): at that time the task wakes back onto Today. POST /tasks/{id}/later is a shortcut.
• PATCH changes only the fields you send; send null to clear one.

Avoiding lost updates

Every task has a version, also sent as the ETag header. Send it back in If-Match on PATCH, DELETE or an action. If the task changed in the meantime (for example in the app), you get 412 precondition_failed with the current task — re-apply your change to it and retry.

curl -X PATCH https://api.nyblit.app/v1/tasks/{id} \
  -H "Authorization: Bearer nyb_pat_…" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "10381"' \
  -d '{"due_date": "2026-10-02"}'

Safe retries

Send an Idempotency-Key (any unique string, such as a UUID) when creating a task. If the request times out, retry with the same key: you get the task the first attempt created (200 with Idempotent-Replayed: true) instead of a duplicate. Use a new key for each new task.

Pagination

Lists return up to limit items (default 50, maximum 100) plus has_more and next_cursor. Pass next_cursor back as cursor to get the next page. Cursors are opaque — do not build them yourself.

{
  "object": "list",
  "data": [ { "object": "task", "id": "…", "title": "Call the bank", … } ],
  "has_more": true,
  "next_cursor": "WyIyMDI2LTA5LTI5…"
}

Unknown query parameters are rejected with 400, so a typo never silently returns everything.

Errors

Errors use RFC 9457 problem details (application/problem+json). Branch on code; show title to people; quote request_id when you contact us.

{
  "type": "https://developers.nyblit.app/errors/insufficient_scope",
  "title": "Token is missing a required scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This endpoint needs the `tasks:read` scope.",
  "request_id": "5f0c…"
}

Rate limits

Limits apply per token, per account and (for writes) per day. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds). When you hit a limit you get 429 with Retry-After — wait that long, then retry. Limits can change, so read the headers rather than hard-coding numbers.

End-to-end encrypted accounts

If an account has end-to-end encryption turned on, task titles and notes are sealed with a key only the owner holds. Nyblit cannot read them, so the API cannot either: requests for those accounts return 403 vault_account_unsupported. We never ask for your recovery key.

Versioning

The major version is in the URL (/v1). We add fields and endpoints without notice, so ignore fields you do not recognise. Breaking changes ship as a new version, announced in advance with Deprecation and Sunset headers.