Miira · leads & WhatsApp v1 read-only
miira.
Reads the Miira lead funnel by stage (the same rule as the board), how many leads are qualified, how many came in this month and the 15 most recent with their stage. Clients who already bought are in the CRM, not here.
Last updated
POST /api/v1/reads/miira.funnel_get- Token scope
miira.funnel_get@1- Workspace permission
api.miira.funnel_getoff by default- Who reads
- The person behind the token, with their role. Someone who leaves the workspace stops reading.
Three permissions
A token with that scope, the workspace owner having switched the read on, and the person's role seeing it in the product. None of them is enough alone. OAuth only →
Request
No fields.
Response — output when status is done
| field | type | rules | |
|---|---|---|---|
leadsInFunnel | integer | required | ≥ 0 |
totalIsMinimum | boolean | required | |
byStage | object[] | required | |
qualified | integer | required | ≥ 0 |
enteredThisMonth | integer | required | ≥ 0 |
recent | object[] | required |
byStage[]
| field | type | rules | |
|---|---|---|---|
stage | string | required | |
qualified | boolean | required | |
leads | integer | required | ≥ 0 |
recent[]
| field | type | rules | |
|---|---|---|---|
name | string | null | required | |
stage | string | null | required | |
enteredOn | string | required | ^\d{4}-\d{2}-\d{2}$ |
Example
# Reads take an OAuth access token, not an API key, and no idempotency key: reading changes nothing.
curl -X POST https://niiko.org/api/v1/reads/miira.funnel_get \
-H "Authorization: Bearer $NIIKO_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
# 200 → done · 4xx → refused, with a named reasonWhy it may refuse
Each reason names who can fix it and how; detail.message, when present, says what to do. Refusals & HTTP codes →
invalid_inputrole_forbiddengrant_offreads_need_a_person
In the clients
| @vorluno/niiko-sdk | niiko.getFunnel() |
| niiko (Python) | niiko.get_funnel() from 0.3.0 · not on the registry yet |
| niiko-cli | niiko read miira.funnel_get |
| n8n-nodes-niiko | No reads: the node holds a key, and reading needs a person through OAuth. |
| niiko-mcp-server | miira_funnel_get readOnlyHint |
History
- The SDKs and the CLI read
@vorluno/niiko-sdk,niikoandniiko-cli0.3.0 take an OAuth access token (accessToken,access_token=,niiko login --token) and have one read-only method per read:getCollections(),get_collections(),niiko read kiipu.collections_get. A read has two outcomes, done or refused, and takes no idempotency key. - Declared reads, OAuth only
POST /api/v1/reads/{id}answers nine declared reads — what is owed, what was collected, the agenda, the funnel, the month — never raw tables and never text someone wrote. Only with an OAuth token, on behalf of a person and with their role (an API key getsreads_need_a_person); each read has its own workspace switch, off by default. The MCP server lists them as read-only tools.