Beta

Build on Nyblit

The Nyblit API lets you read and manage your Tasks from scripts, automations and your own apps. It is a JSON REST API authenticated with personal access tokens.

Base URL https://api.nyblit.app/v1
Needs a plan that includes API Access, on a standard (not end-to-end encrypted) account
Reference every endpoint and field

Quickstart

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
Check it works:

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

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_…"

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.

Scope	Allows
`tasks:read`	Read your tasks.
`tasks:write`	Create, update and delete your tasks.
`projects:read`	Read your projects.
`projects:write`	Create, update and delete your projects.
`workflows:read`	Read your Workflows and Statuses.
`workflows:write`	Create, update and delete your Workflows and Statuses.
`webhooks:manage`	Manage webhook subscriptions.

During the beta the API is read-only: your tasks (with their steps), projects, workflows, statuses and dispositions. Write endpoints and webhooks follow.

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…"
}

Code	Status	Meaning
`invalid_request`	400	A parameter is missing, malformed or unknown. See errors[].
`invalid_token`	401	The token is missing, wrong, expired or revoked.
`insufficient_scope`	403	The token works but lacks the scope this endpoint needs.
`plan_required`	403	The account’s plan does not include API Access.
`access_disabled`	403	Nyblit has turned off API access for this account. Contact support.
`vault_account_unsupported`	403	The account uses end-to-end encryption.
`not_found`	404	No such endpoint or resource (or it belongs to someone else).
`rate_limited`	429	Too many requests. Wait Retry-After seconds.
`internal_error`	500	Our fault. Retry with backoff and quote request_id if it persists.
`api_disabled`	503	The API is temporarily switched off. Retry later.

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.