Ciita · scheduling v1 read-only
ciita.
Reads the appointments of today, this week, next week or this month: how many per status and the first 15 with day, time in the workspace time zone, client, resource and status. Books nothing.
Last updated
POST /api/v1/reads/ciita.agenda_get- Token scope
ciita.agenda_get@1- Workspace permission
api.ciita.agenda_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
| field | type | rules | |
|---|---|---|---|
period | "today" | "this_week" | "next_week" | "this_month" | optional |
Response — output when status is done
| field | type | rules | |
|---|---|---|---|
period | "today" | "this_week" | "next_week" | "this_month" | required | |
today | string | required | ^\d{4}-\d{2}-\d{2}$ |
periodStart | string | required | ^\d{4}-\d{2}-\d{2}$ |
periodEnd | string | required | ^\d{4}-\d{2}-\d{2}$ |
timeZone | string | required | |
appointments | integer | required | ≥ 0 |
byStatus | map<string, unknown> | required | |
totalIsMinimum | boolean | required | |
first | object[] | required |
first[]
| field | type | rules | |
|---|---|---|---|
date | string | required | ^\d{4}-\d{2}-\d{2}$ |
time | string | required | ^\d{2}:\d{2}$ |
client | string | null | required | |
resource | string | null | required | |
status | string | required |
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/ciita.agenda_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.getAgenda() |
| niiko (Python) | niiko.get_agenda() from 0.3.0 · not on the registry yet |
| niiko-cli | niiko read ciita.agenda_get |
| n8n-nodes-niiko | No reads: the node holds a key, and reading needs a person through OAuth. |
| niiko-mcp-server | ciita_agenda_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.