Nirvana Counts API
The Counts API from Nirvana — 1 operation(s) for counts.
The Counts API from Nirvana — 1 operation(s) for counts.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/nirvanahq-com:nirvanahq-com-counts-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Nirvana Task Counts API
version: 1.0.0-beta
description: 'Nirvana Task API (Public Beta). Clean REST endpoints for integrations, automation, and AI agents (MCP servers, scripts, webhooks). Auth: `Bearer `. Legacy v0 endpoints are removed from this service; migrate integrations to /v1/* endpoints. During beta, backward compatibility is best-effort and minor response changes may occur before GA.'
servers:
- url: https://api.nirvanahq.com
security:
- bearerAuth: []
tags:
- name: Counts
paths:
/v1/counts:
get:
operationId: v1GetCounts
summary: Task counts per GTD state
description: 'Returns task counts per GTD state for a quick system overview. "focus" is the starred/Focus list count. With `profile=mcp`, returns `McpCountsResponse` instead: each list''s count with the search query that produces it (searching that query returns exactly that many tasks), due-today sub-counts, and weekly-review checks. It takes the search clock and scope parameters (`now`, `tz`, `weekstart`, `area`, `areamode`).'
tags:
- Counts
parameters:
- name: profile
in: query
description: '`mcp` for counts built from search queries. Omit for the legacy counts.'
schema:
type: string
enum:
- mcp
- $ref: '#/components/parameters/Now'
- $ref: '#/components/parameters/Tz'
- $ref: '#/components/parameters/Weekstart'
- $ref: '#/components/parameters/Area'
- $ref: '#/components/parameters/Areamode'
responses:
'200':
description: Counts per state, or the query-backed counts with profile=mcp
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/McpCountsResponse'
- type: object
required:
- ok
- counts
properties:
ok:
type: boolean
counts:
type: object
properties:
inbox:
type: integer
next:
type: integer
waiting:
type: integer
scheduled:
type: integer
someday:
type: integer
later:
type: integer
focus:
type: integer
projects:
type: integer
reflists:
type: integer
trash:
type: integer
example:
ok: true
counts:
inbox: 1
next: 40
waiting: 0
scheduled: 0
someday: 3
later: 0
focus: 33
projects: 7
reflists: 4
trash: 0
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/TooManyTasks'
components:
responses:
TooManyTasks:
description: 'Search, counts or vocabulary declined: the account has more rows to search than the server reads at once (20,000 by default). Retrying or narrowing the query does not help; the whole account is loaded before filtering.
'
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
code:
type: string
enum:
- too_many_tasks
limit:
type: integer
error:
type: string
example:
ok: false
code: too_many_tasks
limit: 20000
error: This account has more than 20,000 tasks to search, more than search can read at once. This usually means repeating tasks or an automation have built up a large backlog. Contact Nirvana support at support@nirvanahq.com and we can help clean it up.
Unauthorized:
description: Missing or invalid Bearer token
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: Unauthorized
BadRequest:
description: Invalid request (body or query parameters)
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
code:
type: string
description: Search-grammar reads only (search mode, profile=mcp). `invalid_request` for a bad parameter; `unknown_view`, `invalid_cursor` or `cursor_mismatch` for a bad view or cursor.
error:
type: string
example:
ok: false
error: name is required
parameters:
Area:
name: area
in: query
description: Grammar reads only (search mode, profile=mcp). Area scope (all, none or an area name). Default all.
schema:
type: string
Areamode:
name: areamode
in: query
description: Grammar reads only (search mode, profile=mcp). Whether rows with no area stay in an area scope. Defaults to the user's stored area-filtering preference (exclusive when unset).
schema:
type: string
enum:
- inclusive
- exclusive
Tz:
name: tz
in: query
description: Grammar reads only (search mode, profile=mcp). IANA zone or UTC offset for "today". Default the user's stored GMT offset.
schema:
type: string
Now:
name: now
in: query
description: Grammar reads only (search mode, profile=mcp). The evaluation instant (ISO 8601 with offset). Default the server clock.
schema:
type: string
Weekstart:
name: weekstart
in: query
description: Grammar reads only (search mode, profile=mcp). First day of the week for week ranges. Defaults to the user's stored week start (sun when unset).
schema:
type: string
enum:
- sun
- mon
schemas:
McpScope:
type: object
properties:
area:
type: string
areamode:
type:
- string
- 'null'
enum:
- inclusive
- exclusive
- null
McpCountsResponse:
type: object
required:
- ok
- grammar_version
- lists
description: 'GET /v1/counts?profile=mcp: each count is the total of its `query` (and `due` of its `due_query`), so an agent can list exactly what it counted. Finished work is not a list here; ask is:done.
'
properties:
ok:
type: boolean
grammar_version:
type: integer
today:
type: string
format: date
timezone:
type: string
scope:
$ref: '#/components/schemas/McpScope'
lists:
type: array
items:
type: object
properties:
list:
type: string
enum:
- inbox
- focus
- next
- later
- waiting
- scheduled
- someday
- projects
- reference
- trash
count:
type: integer
query:
type: string
due:
type: integer
due_query:
type: string
feature_off:
type: boolean
description: Present (true) when the account has this list's feature turned off (Settings > Workflow > Features) but the list still holds items. A switched-off list that is empty is not listed at all; Focus switched off is never listed (its tasks are in Next). Later is off unless the account enabled it.
note:
type: string
description: 'With feature_off: what to tell the user (the feature is off; N items remain; help re-file them).'
review:
type: array
items:
type: object
properties:
check:
type: string
count:
type: integer
query:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer