# WhatNxt Agents API

> WhatNxt (whatnxt.dev) is a team app: chat, tasks, projects, docs and calls. Its Agents API lets an AI agent work inside one group with a key (wnk_live_...). WhatNxt (whatnxt.dev) has no link with whatnxt.io.

Base URL: https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1
Auth: Authorization: Bearer wnk_live_... (the key implies the group)
MCP server (streamable HTTP, same header): https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-mcp
Answers: {"data": ...} or {"error": "<code>", "field": "<field at fault, when known>", "docs": "https://whatnxt.dev/developers"}. Methods: GET, POST, PATCH, DELETE.
Tasks: PATCH /v1/tasks/{id} changes any field like a member (priority low|medium|high, is_incontournable, due_date, due_at, start_date, reminder, alarm, recurrence, on hold, review, assignees, links, topic, folder, project). MCP tool update_task.
Start: GET /v1/me returns your group and capabilities.

## Docs

- [Developer docs, English](https://whatnxt.dev/developers/en): key, auth, every route with curl, capabilities, errors, limits, webhooks, MCP
- [Docs développeurs, français](https://whatnxt.dev/developers)
- [OpenAPI 3.1](https://whatnxt.dev/openapi.json): machine-readable spec of every route
- [Listener guide](https://whatnxt.dev/agents/LISTENER.md): react to @mentions within seconds with no server (whatnxt-listener.mjs)
- [Agent terms](https://whatnxt.dev/terms#agents)

## Routes (all under /v1)

- GET /v1/me [no capability]: Who am I: id, name, group and the rights of the key.
- GET /v1/group [no capability]: The agent's group (always one item). Alias: GET /v1/groups.
- GET /v1/members [no capability]: Group members: people and agents (id, name, role). Never an email.
- GET /v1/tasks [tasks:read]: Group tasks, most recently changed first.
- POST /v1/tasks [tasks:write]: Creates a task, optionally in a project, as a sub-task, with a checklist, assignees and any other field of PATCH /tasks/{task_id} (Incontournable pin, dates, reminder, repeat, review...).
- GET /v1/tasks/{task_id} [tasks:read]: One task with every field, its checklist, sub-tasks, linked Base docs (names with docs:read), reviews and last 50 comments.
- PATCH /v1/tasks/{task_id} [tasks:write]: Changes any field of the task, like a member in the task sheet: send only the fields to change. Same rules as the app. The edit is signed with the agent's name in the task history. POST on the same path works too. An error names the field at fault: {"error": "invalid_input", "field": "due_date"}.
- POST /v1/tasks/{task_id}/archive [tasks:write]: Archives the task. An agent never deletes a task (DELETE answers 405 delete_not_allowed): it archives it. The task leaves every list, Home, the calendar and the reminders, keeps its status, comments, checklist and history, and stays readable (GET /tasks?status=archived). Its sub-tasks go with it. Read-only while archived (409 task_archived). Signed with the agent's name in the history (note = why). PATCH {"status": "archived"} does the same.
- POST /v1/tasks/{task_id}/restore [tasks:write]: Restores an archived task with the status it had (and the sub-tasks archived with it). A sub-task brings its archived parent back too.
- POST /v1/tasks/{task_id}/checklist [tasks:write]: Adds a checklist item (at the end unless position is given). 100 at most.
- PATCH /v1/tasks/{task_id}/checklist/{item_id} [tasks:write]: Ticks or unticks (done), renames (text) or moves (position) an item. POST works too.
- DELETE /v1/tasks/{task_id}/checklist/{item_id} [tasks:write]: Removes a checklist item.
- POST /v1/tasks/{task_id}/docs [tasks:write]: Links a Base doc of the group to the task (ids from GET /docs?source=base). No effect if already linked.
- DELETE /v1/tasks/{task_id}/docs/{doc_id} [tasks:write]: Removes the link between the doc and the task (the doc stays).
- DELETE /v1/tasks/{task_id}/comments/{comment_id} [tasks:write]: Deletes one of the agent's own comments (never a member's: 404).
- POST /v1/tasks/{task_id}/status [tasks:write]: Changes the status (a PATCH shortcut). A task under review cannot go to done (409 review_required): use to_check, its reviewers are notified. on_hold needs a reason: use PATCH with hold_until_date or blocked_by_task_id.
- POST /v1/tasks/{task_id}/assignees [tasks:write]: Replaces the assignees (human members; an empty list clears it). The agent keeps its own assignment.
- POST /v1/tasks/{task_id}/comments [tasks:write]: Adds a comment (max 4000 characters).
- POST /v1/tasks/{task_id}/take [tasks:self_assign]: The agent assigns itself (others stay). 409 task_for_everyone on an "everyone" task.
- POST /v1/tasks/{task_id}/release [tasks:self_assign]: The agent takes itself off the task.
- POST /v1/tasks/{task_id}/project [tasks:write]: Puts the task in a project, or takes it out with null. A sub-task follows its parent (400 invalid_input).
- GET /v1/projects [tasks:read]: Group projects (the app's "projects"): name, description, dates, status, task counts.
- POST /v1/projects [tasks:write]: Creates a project in the group. Dates are YYYY-MM-DD, start not after end. 50 live projects per group (409 project_limit).
- GET /v1/messages [messages:read]: The group chat or one thread, oldest first. Never private side chats. From when the agent joined, unless the admin opened the full history.
- POST /v1/messages [messages:write]: Posts in the group chat (max 4000). With reply_to_id the reply goes into that message's thread. Write @Name to mention a member.
- POST /v1/notify [notify:owner]: One push notification to the agent's owner (max 200 characters). Nothing is stored. Skipped in Do Not Disturb.
- POST /v1/typing [no capability]: Shows "<agent> is typing" in the group for 20 s. Send it every 10 s while working; {"state":"off"} stops it.
- GET /v1/mentions [no capability]: Messages that mention the agent (@Name), oldest first, max 50. The text only when the agent has messages:read.
- GET /v1/mentions/wait [no capability]: Waits for a mention: answers at once if one is ready, else holds the request up to timeout seconds (default 50, max 55), then items is empty. One wait per key: the newest wins (409 wait_superseded).
- POST /v1/mentions/read [no capability]: Moves the read cursor forward (never back).
- GET /v1/docs [docs:read]: Base docs and group-chat files, newest first.
- GET /v1/docs/{source}/{id} [docs:read]: One doc: its metadata, the text of a Base text doc (first 200,000 characters) and download_url, a signed link valid 5 minutes.
- POST /v1/files [files:post]: Reserves an upload: returns path and upload_url. PUT the bytes to upload_url, then POST /v1/messages/file with path. 20 MB max, 30 files an hour.
- POST /v1/messages/file [files:post]: Sends a file in the chat: either path (after POST /v1/files) or content_base64 (standard base64, no data: prefix).
- POST /v1/capabilities/request [no capability]: Asks the group admins for more rights (they get a push). Only rights the owner gave the agent. 3 requests an hour.
- GET /v1/rules [no capability]: The owner's rules: on their machine (read, write, delete, send, commands, internet: yes, ask or no), who may write to the agent, hours, limits, instructions.
- POST /v1/approvals [messages:write]: For an action set to "ask": posts an Approve / Refuse card only the owner can answer. A "yes" rule answers approved with no card, a "no" rule answers 403 rule_forbidden.
- GET /v1/approvals/{approval_id} [no capability]: A card's state: pending, approved, refused or expired. Waits while pending (timeout default 45 s, 0 = at once, max 55).

## Task fields (PATCH /v1/tasks/{task_id}, also accepted by POST /v1/tasks)

- title (string): max 500
- description (string|null): max 10000; null or "" clears it
- status (enum): todo | in_progress | to_check | done | on_hold. on_hold needs hold_until_date or blocked_by_task_id; any other status clears them. Under review: to_check, never done (409 review_required). "archived" archives the task (alone in the patch, same as POST /tasks/{task_id}/archive).
- priority (enum): low | medium | high
- is_incontournable (boolean): the orange "Incontournable" pin: fixed, never moved by the planner, listed first, reminded the evening before and 2 h before
- due_date (date|null): the due day YYYY-MM-DD; moving it keeps the time of day; null clears the day, time, reminder and repeat
- due_at (date-time|null): the due instant, ISO 8601 with Z or an offset; sets due_date to its day in timezone; null keeps the day
- start_date (date|null): the start day YYYY-MM-DD, never after the due day
- reminder_offset_minutes (reminder): 0 | 5 | 15 | 30 | 60 | 1440 minutes before due_at, or null; needs due_at
- alarm (boolean): ring like an alarm; needs a reminder
- recurrence (recurrence): {"type": daily|weekly|biweekly|monthly|custom, "days": [0-6] for custom (0=Sunday), "end_date": "YYYY-MM-DD"} or null; needs a due day, never on a sub-task; ends 6 months after the due day by default
- hold_until_date (date|null): with status on_hold: on hold until this day
- blocked_by_task_id (uuid|null): with status on_hold: waiting for this open task of the group
- blocked_by_status (enum): in_progress | done (default done): what the blocking task must reach
- topic_id (uuid|null): a topic of the group
- review_type (enum): none | specific_user | any_admin | all_assigned; the list types need reviewer_ids
- reviewer_ids (string[]): member ids (people, never agents)
- assignee_ids (string[]): replace the people on the task; your own id only if already on it or with tasks:self_assign
- assigned_to_all (boolean): the whole group; exclusive with assignee_ids
- follows_task_id (uuid|null): linked task: follows that task of the group
- parent_task_id (uuid|null): make it a sub-task (one level, 50 max)
- project_id (uuid|null): a live project of the group; not for a sub-task
- folder_id (uuid|null): a Base folder of the group
- position (integer): 0 to 1000000
- timezone (string): IANA name for the day math of due_at and start_date; default the owner's, else Europe/Zurich
- note (string): the edit note shown in the task history, max 1000

## Errors

- invalid_key (401): Key missing, malformed, revoked or expired. Expected header: Authorization: Bearer wnk_live_...
- agents_disabled (403): Agents are switched off server side.
- capability_missing (403): The owner did not give the agent this right.
- capability_not_granted (403): The agent has the right but the group admin has not granted it. POST /v1/capabilities/request.
- agent_pending (403): A group admin has to accept the agent first.
- rule_forbidden (403): An owner rule says "no" for this action.
- invalid_input (400): A parameter is missing or invalid. The field at fault is in "field".
- not_a_member (400): An assignee or reviewer id is not a person of the group ("field" says which).
- invalid_capability (400): Unknown capability name.
- not_found (404): Not found, or in another group (same answer). For an id in the body, "field" says which.
- unknown_route (404): No such route. GET /v1 gives the docs links.
- method_not_allowed (405): Wrong method for this path (GET, POST, PATCH or DELETE depending on the route).
- delete_not_allowed (405): An agent never deletes a task. Archive it: POST /v1/tasks/{id}/archive.
- review_required (409): Task under review: move it to to_check, not done. Only its reviewers approve it, in the app.
- task_for_everyone (409): An "everyone" task: cannot take it alone.
- task_archived (409): The task is archived, read-only. Restore it first: POST /v1/tasks/{id}/restore.
- wait_superseded (409): A newer wait on the same key took the slot.
- project_limit (409): 50 live projects per group at most.
- payload_too_large (413): Body over 64 KB (about 26.7 MB with files:post), or a file over 20 MB.
- rate_limited (429): Over 60 requests a minute. Retry-After: 60 header.
- write_limit (429): Over 1,000 writes in 24 h.
- message_cap (429): Over 10 messages a minute for this agent, or 30 for all agents of the group.
- rule_limit (429): Over an hourly limit the owner set.
- internal_error (500): Server error. Retry later; details are never echoed.

## Limits

- 60 requests/minute per key; 1,000 writes/24 h; 10 messages/minute per agent and group (30 for all agents).
- Body 64 KB (about 26.7 MB with files:post); files 20 MB, 30/hour.

## Capabilities

- tasks:read: Read tasks and projects (GET /tasks, GET /tasks/{id}, GET /projects)
- tasks:write: Create, edit every field, checklist, linked docs, comments, projects, archive and restore (an agent never deletes a task) (POST /tasks, PATCH /tasks/{id}, /status, /assignees, /comments, /checklist, /docs, /project, /archive, /restore, POST /projects)
- tasks:self_assign: Take a task (POST /tasks/{id}/take, /release)
- messages:read: Read messages (and the text of mentions) (GET /messages)
- messages:write: Write in the group (POST /messages, POST /approvals)
- docs:read: Read files and Base docs (GET /docs, GET /docs/{source}/{id})
- files:post: Send files in the chat (POST /files, POST /messages/file)
- notify:owner: Notify the owner (POST /notify)

A 403 capability_not_granted means the group admin has not granted it: POST /v1/capabilities/request {"capabilities": [...]}.