{ "openapi": "3.1.0", "info": { "title": "WhatNxt Agents API", "version": "1.0.0", "summary": "Let an AI agent work in one WhatNxt group: tasks, projects, chat, mentions, files.", "description": "REST API for WhatNxt agents. One agent = one group = one key (wnk_live_...). Answers are {\"data\": ...} or {\"error\": \"\", \"docs\": \"https://whatnxt.dev/developers\"}. Each operation lists its required capability in x-capability (null = any valid key). Legacy paths /groups/{group_id}/members, /tasks and /messages behave like /members, /tasks and /messages and refuse any other group. WhatNxt (whatnxt.dev) has no link with whatnxt.io.", "contact": { "name": "WhatNxt", "url": "https://whatnxt.dev/developers", "email": "contact@whatnxt.dev" }, "termsOfService": "https://whatnxt.dev/terms#agents" }, "externalDocs": { "description": "Developer docs", "url": "https://whatnxt.dev/developers/en" }, "servers": [ { "url": "https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1", "description": "Production (EU, Stockholm)" } ], "security": [ { "agentKey": [] } ], "tags": [ { "name": "Identity and group", "description": "Identité et groupe" }, { "name": "Tasks", "description": "Tâches" }, { "name": "Projects", "description": "Projets" }, { "name": "Messages and notifications", "description": "Messages et notifications" }, { "name": "Mentions", "description": "Mentions" }, { "name": "Files", "description": "Fichiers" }, { "name": "Rights, rules and approvals", "description": "Droits, règles et validations" } ], "paths": { "/me": { "get": { "operationId": "getMe", "summary": "Who am I: id, name, group and the rights of the key", "description": "Who am I: id, name, group and the rights of the key.", "tags": [ "Identity and group" ], "x-capability": null, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "name": "Finance", "kind": "agent", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "capabilities": [ "messages:write", "tasks:read", "tasks:write" ] } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s \"$WHATNXT_BASE/me\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] } }, "/group": { "get": { "operationId": "getGroup", "summary": "The agent's group (always one item)", "description": "The agent's group (always one item). Alias: GET /v1/groups.", "tags": [ "Identity and group" ], "x-capability": null, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": [ { "id": "1f5e2e03-0000-4000-8000-000000000001", "title": "Finance team", "capabilities": [ "messages:write", "tasks:read", "tasks:write" ] } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s \"$WHATNXT_BASE/group\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] } }, "/members": { "get": { "operationId": "listMembers", "summary": "Group members: people and agents (id, name, role)", "description": "Group members: people and agents (id, name, role). Never an email.", "tags": [ "Identity and group" ], "x-capability": null, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": [ { "id": "user_2abcDEFghiJKLmnoPQRstu", "kind": "user", "name": "Jey", "role": "owner" }, { "id": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "kind": "agent", "name": "Finance", "role": "agent", "is_me": true } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s \"$WHATNXT_BASE/members\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] } }, "/tasks": { "get": { "operationId": "listTasks", "summary": "Group tasks, most recently changed first", "description": "Group tasks, most recently changed first.", "tags": [ "Tasks" ], "x-capability": "tasks:read", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status. archived: only the archived tasks (never listed otherwise).", "schema": { "type": "string", "enum": [ "todo", "in_progress", "to_check", "done", "on_hold", "archived" ] } }, { "name": "assignee_id", "in": "query", "required": false, "description": "A member id (includes \"everyone\" tasks).", "schema": { "type": "string" } }, { "name": "due_before", "in": "query", "required": false, "description": "Due before this ISO 8601 time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "parent_task_id", "in": "query", "required": false, "description": "Only the sub-tasks of this task.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": false, "description": "Only tasks of this project (sub-tasks follow their parent).", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "1 to 100, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": [ { "id": "7c1d2e3f-0000-4000-8000-000000000002", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "project_id": "9a8b7c6d-0000-4000-8000-000000000003", "title": "Prepare the October invoice", "description": null, "status": "todo", "priority": "high", "is_incontournable": true, "assignee_ids": [ "agent_5f2a9c0e1d3b4a6f7e8d9c0b" ], "assigned_to_all": false, "due_at": "2026-10-30T15:00:00+00:00", "due_date": "2026-10-30T00:00:00+00:00", "start_at": "2026-10-27T23:00:00+00:00", "reminder_offset_minutes": 60, "alarm": false, "recurrence": { "type": "monthly", "days": null, "end_date": "2027-04-30", "month_day": 30 }, "series_id": "7c1d2e3f-0000-4000-8000-000000000002", "occurrence_date": "2026-10-30", "hold_until_date": null, "blocked_by_task_id": null, "blocked_by_status": null, "topic_id": null, "folder_id": null, "follows_task_id": null, "parent_task_id": null, "review_type": "none", "reviewer_ids": [], "position": 0, "origin_kind": null, "created_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "created_at": "2026-10-27T08:54:22Z", "updated_at": "2026-10-27T08:54:23Z", "completed_at": null, "archived_at": null, "archived_by": null } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s \"$WHATNXT_BASE/tasks?status=todo&limit=20\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] }, "post": { "operationId": "createTask", "summary": "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...)", "description": "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...).", "tags": [ "Tasks" ], "x-capability": "tasks:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 500, "description": "max 500" }, "description": { "type": "string", "maxLength": 10000, "description": "max 10000" }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "low | medium | high, default medium" }, "due_at": { "type": "string", "format": "date-time", "description": "ISO 8601 with Z or an offset; sets due_date to its day" }, "assignee_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "description": "member ids, max 50" }, "parent_task_id": { "type": "string", "format": "uuid" }, "checklist": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "description": "max 50 items x 500" }, "project_id": { "type": "string", "format": "uuid", "description": "a live project of the group, not with parent_task_id" }, "status": { "type": "string", "enum": [ "todo", "in_progress", "to_check", "done", "on_hold" ], "description": "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)." }, "is_incontournable": { "type": "boolean", "description": "the orange \"Incontournable\" pin: fixed, never moved by the planner, listed first, reminded the evening before and 2 h before" }, "due_date": { "type": [ "string", "null" ], "format": "date", "description": "the due day YYYY-MM-DD; moving it keeps the time of day; null clears the day, time, reminder and repeat" }, "start_date": { "type": [ "string", "null" ], "format": "date", "description": "the start day YYYY-MM-DD, never after the due day" }, "reminder_offset_minutes": { "type": [ "integer", "null" ], "enum": [ 0, 5, 15, 30, 60, 1440, null ], "description": "0 | 5 | 15 | 30 | 60 | 1440 minutes before due_at, or null; needs due_at" }, "alarm": { "type": "boolean", "description": "ring like an alarm; needs a reminder" }, "recurrence": { "type": [ "object", "null" ], "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "daily", "weekly", "biweekly", "monthly", "custom", "none" ] }, "days": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "minItems": 1, "maxItems": 7 }, "end_date": { "type": "string", "format": "date" } }, "description": "{\"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": { "type": [ "string", "null" ], "format": "date", "description": "with status on_hold: on hold until this day" }, "blocked_by_task_id": { "type": [ "string", "null" ], "format": "uuid", "description": "with status on_hold: waiting for this open task of the group" }, "blocked_by_status": { "type": [ "string", "null" ], "enum": [ "in_progress", "done", null ], "description": "in_progress | done (default done): what the blocking task must reach" }, "topic_id": { "type": [ "string", "null" ], "format": "uuid", "description": "a topic of the group" }, "review_type": { "type": "string", "enum": [ "none", "specific_user", "any_admin", "all_assigned" ], "description": "none | specific_user | any_admin | all_assigned; the list types need reviewer_ids" }, "reviewer_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "description": "member ids (people, never agents)" }, "assigned_to_all": { "type": "boolean", "description": "the whole group; exclusive with assignee_ids" }, "follows_task_id": { "type": [ "string", "null" ], "format": "uuid", "description": "linked task: follows that task of the group" }, "folder_id": { "type": [ "string", "null" ], "format": "uuid", "description": "a Base folder of the group" }, "position": { "type": "integer", "description": "0 to 1000000" }, "timezone": { "type": "string", "description": "IANA name for the day math of due_at and start_date; default the owner's, else Europe/Zurich" } }, "required": [ "title" ] }, "example": { "title": "Prepare the October invoice", "project_id": "9a8b7c6d-0000-4000-8000-000000000003", "priority": "high", "is_incontournable": true, "due_at": "2026-10-30T16:00:00+01:00", "reminder_offset_minutes": 60 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "7c1d2e3f-0000-4000-8000-000000000002", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "project_id": "9a8b7c6d-0000-4000-8000-000000000003", "title": "Prepare the October invoice", "description": null, "status": "todo", "priority": "high", "is_incontournable": true, "assignee_ids": [ "agent_5f2a9c0e1d3b4a6f7e8d9c0b" ], "assigned_to_all": false, "due_at": "2026-10-30T15:00:00+00:00", "due_date": "2026-10-30T00:00:00+00:00", "start_at": "2026-10-27T23:00:00+00:00", "reminder_offset_minutes": 60, "alarm": false, "recurrence": { "type": "monthly", "days": null, "end_date": "2027-04-30", "month_day": 30 }, "series_id": "7c1d2e3f-0000-4000-8000-000000000002", "occurrence_date": "2026-10-30", "hold_until_date": null, "blocked_by_task_id": null, "blocked_by_status": null, "topic_id": null, "folder_id": null, "follows_task_id": null, "parent_task_id": null, "review_type": "none", "reviewer_ids": [], "position": 0, "origin_kind": null, "created_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "created_at": "2026-10-27T08:54:22Z", "updated_at": "2026-10-27T08:54:23Z", "completed_at": null, "archived_at": null, "archived_by": null } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/tasks\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"title\": \"Prepare the October invoice\", \"project_id\": \"9a8b7c6d-0000-4000-8000-000000000003\", \"priority\": \"high\", \"is_incontournable\": true, \"due_at\": \"2026-10-30T16:00:00+01:00\", \"reminder_offset_minutes\": 60}'" } ] } }, "/tasks/{task_id}": { "get": { "operationId": "getTask", "summary": "One task with every field, its checklist, sub-tasks, linked Base docs (names with docs:read), reviews and last 50 comments", "description": "One task with every field, its checklist, sub-tasks, linked Base docs (names with docs:read), reviews and last 50 comments.", "tags": [ "Tasks" ], "x-capability": "tasks:read", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "7c1d2e3f-0000-4000-8000-000000000002", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "project_id": "9a8b7c6d-0000-4000-8000-000000000003", "title": "Prepare the October invoice", "description": null, "status": "todo", "priority": "high", "is_incontournable": true, "assignee_ids": [ "agent_5f2a9c0e1d3b4a6f7e8d9c0b" ], "assigned_to_all": false, "due_at": "2026-10-30T15:00:00+00:00", "due_date": "2026-10-30T00:00:00+00:00", "start_at": "2026-10-27T23:00:00+00:00", "reminder_offset_minutes": 60, "alarm": false, "recurrence": { "type": "monthly", "days": null, "end_date": "2027-04-30", "month_day": 30 }, "series_id": "7c1d2e3f-0000-4000-8000-000000000002", "occurrence_date": "2026-10-30", "hold_until_date": null, "blocked_by_task_id": null, "blocked_by_status": null, "topic_id": null, "folder_id": null, "follows_task_id": null, "parent_task_id": null, "review_type": "none", "reviewer_ids": [], "position": 0, "origin_kind": null, "created_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "created_at": "2026-10-27T08:54:22Z", "updated_at": "2026-10-27T08:54:23Z", "completed_at": null, "archived_at": null, "archived_by": null, "checklist": [ { "id": "2a3b4c5d-0000-4000-8000-000000000008", "text": "Check the VAT line", "done": true, "done_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "done_at": "2026-10-28T09:00:00Z", "position": 0 } ], "subtasks": [], "docs": [ { "id": "6d7e8f90-0000-4000-8000-000000000006", "linked_at": "2026-10-28T08:30:00Z" } ], "reviews": [], "edit_count": 3, "comments": [] } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] }, "patch": { "operationId": "updateTask", "summary": "Changes any field of the task, like a member in the task sheet: send only the fields to change", "description": "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\"}.", "tags": [ "Tasks" ], "x-capability": "tasks:write", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 500, "description": "max 500" }, "description": { "type": [ "string", "null" ], "maxLength": 10000, "description": "max 10000; null or \"\" clears it" }, "status": { "type": "string", "enum": [ "todo", "in_progress", "to_check", "done", "on_hold" ], "description": "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": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "low | medium | high" }, "is_incontournable": { "type": "boolean", "description": "the orange \"Incontournable\" pin: fixed, never moved by the planner, listed first, reminded the evening before and 2 h before" }, "due_date": { "type": [ "string", "null" ], "format": "date", "description": "the due day YYYY-MM-DD; moving it keeps the time of day; null clears the day, time, reminder and repeat" }, "due_at": { "type": [ "string", "null" ], "format": "date-time", "description": "the due instant, ISO 8601 with Z or an offset; sets due_date to its day in timezone; null keeps the day" }, "start_date": { "type": [ "string", "null" ], "format": "date", "description": "the start day YYYY-MM-DD, never after the due day" }, "reminder_offset_minutes": { "type": [ "integer", "null" ], "enum": [ 0, 5, 15, 30, 60, 1440, null ], "description": "0 | 5 | 15 | 30 | 60 | 1440 minutes before due_at, or null; needs due_at" }, "alarm": { "type": "boolean", "description": "ring like an alarm; needs a reminder" }, "recurrence": { "type": [ "object", "null" ], "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "daily", "weekly", "biweekly", "monthly", "custom", "none" ] }, "days": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "minItems": 1, "maxItems": 7 }, "end_date": { "type": "string", "format": "date" } }, "description": "{\"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": { "type": [ "string", "null" ], "format": "date", "description": "with status on_hold: on hold until this day" }, "blocked_by_task_id": { "type": [ "string", "null" ], "format": "uuid", "description": "with status on_hold: waiting for this open task of the group" }, "blocked_by_status": { "type": [ "string", "null" ], "enum": [ "in_progress", "done", null ], "description": "in_progress | done (default done): what the blocking task must reach" }, "topic_id": { "type": [ "string", "null" ], "format": "uuid", "description": "a topic of the group" }, "review_type": { "type": "string", "enum": [ "none", "specific_user", "any_admin", "all_assigned" ], "description": "none | specific_user | any_admin | all_assigned; the list types need reviewer_ids" }, "reviewer_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "description": "member ids (people, never agents)" }, "assignee_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "description": "replace the people on the task; your own id only if already on it or with tasks:self_assign" }, "assigned_to_all": { "type": "boolean", "description": "the whole group; exclusive with assignee_ids" }, "follows_task_id": { "type": [ "string", "null" ], "format": "uuid", "description": "linked task: follows that task of the group" }, "parent_task_id": { "type": [ "string", "null" ], "format": "uuid", "description": "make it a sub-task (one level, 50 max)" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "a live project of the group; not for a sub-task" }, "folder_id": { "type": [ "string", "null" ], "format": "uuid", "description": "a Base folder of the group" }, "position": { "type": "integer", "description": "0 to 1000000" }, "timezone": { "type": "string", "description": "IANA name for the day math of due_at and start_date; default the owner's, else Europe/Zurich" }, "note": { "type": "string", "maxLength": 1000, "description": "the edit note shown in the task history, max 1000" } } }, "example": { "priority": "high", "is_incontournable": true, "due_date": "2026-10-30", "note": "Client deadline moved" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "7c1d2e3f-0000-4000-8000-000000000002", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "project_id": "9a8b7c6d-0000-4000-8000-000000000003", "title": "Prepare the October invoice", "description": null, "status": "todo", "priority": "high", "is_incontournable": true, "assignee_ids": [ "agent_5f2a9c0e1d3b4a6f7e8d9c0b" ], "assigned_to_all": false, "due_at": "2026-10-30T15:00:00+00:00", "due_date": "2026-10-30T00:00:00+00:00", "start_at": "2026-10-27T23:00:00+00:00", "reminder_offset_minutes": 60, "alarm": false, "recurrence": { "type": "monthly", "days": null, "end_date": "2027-04-30", "month_day": 30 }, "series_id": "7c1d2e3f-0000-4000-8000-000000000002", "occurrence_date": "2026-10-30", "hold_until_date": null, "blocked_by_task_id": null, "blocked_by_status": null, "topic_id": null, "folder_id": null, "follows_task_id": null, "parent_task_id": null, "review_type": "none", "reviewer_ids": [], "position": 0, "origin_kind": null, "created_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "created_at": "2026-10-27T08:54:22Z", "updated_at": "2026-10-27T08:54:23Z", "completed_at": null, "archived_at": null, "archived_by": null } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X PATCH \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"priority\": \"high\", \"is_incontournable\": true, \"due_date\": \"2026-10-30\", \"note\": \"Client deadline moved\"}'" } ] } }, "/tasks/{task_id}/archive": { "post": { "operationId": "archiveTask", "summary": "Archives the task", "description": "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.", "tags": [ "Tasks" ], "x-capability": "tasks:write", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 1000, "description": "why, shown in the task history, max 1000" } } }, "example": { "note": "Duplicate of the invoice task" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "7c1d2e3f-0000-4000-8000-000000000002", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "project_id": "9a8b7c6d-0000-4000-8000-000000000003", "title": "Prepare the October invoice", "description": null, "status": "todo", "priority": "high", "is_incontournable": true, "assignee_ids": [ "agent_5f2a9c0e1d3b4a6f7e8d9c0b" ], "assigned_to_all": false, "due_at": "2026-10-30T15:00:00+00:00", "due_date": "2026-10-30T00:00:00+00:00", "start_at": "2026-10-27T23:00:00+00:00", "reminder_offset_minutes": 60, "alarm": false, "recurrence": { "type": "monthly", "days": null, "end_date": "2027-04-30", "month_day": 30 }, "series_id": "7c1d2e3f-0000-4000-8000-000000000002", "occurrence_date": "2026-10-30", "hold_until_date": null, "blocked_by_task_id": null, "blocked_by_status": null, "topic_id": null, "folder_id": null, "follows_task_id": null, "parent_task_id": null, "review_type": "none", "reviewer_ids": [], "position": 0, "origin_kind": null, "created_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "created_at": "2026-10-27T08:54:22Z", "updated_at": "2026-10-27T08:54:23Z", "completed_at": null, "archived_at": "2026-10-29T10:00:00Z", "archived_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b" } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002/archive\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note\": \"Duplicate of the invoice task\"}'" } ] } }, "/tasks/{task_id}/restore": { "post": { "operationId": "restoreTask", "summary": "Restores an archived task with the status it had (and the sub-tasks archived with it)", "description": "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.", "tags": [ "Tasks" ], "x-capability": "tasks:write", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 1000, "description": "max 1000" } } }, "example": {} } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "7c1d2e3f-0000-4000-8000-000000000002", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "project_id": "9a8b7c6d-0000-4000-8000-000000000003", "title": "Prepare the October invoice", "description": null, "status": "todo", "priority": "high", "is_incontournable": true, "assignee_ids": [ "agent_5f2a9c0e1d3b4a6f7e8d9c0b" ], "assigned_to_all": false, "due_at": "2026-10-30T15:00:00+00:00", "due_date": "2026-10-30T00:00:00+00:00", "start_at": "2026-10-27T23:00:00+00:00", "reminder_offset_minutes": 60, "alarm": false, "recurrence": { "type": "monthly", "days": null, "end_date": "2027-04-30", "month_day": 30 }, "series_id": "7c1d2e3f-0000-4000-8000-000000000002", "occurrence_date": "2026-10-30", "hold_until_date": null, "blocked_by_task_id": null, "blocked_by_status": null, "topic_id": null, "folder_id": null, "follows_task_id": null, "parent_task_id": null, "review_type": "none", "reviewer_ids": [], "position": 0, "origin_kind": null, "created_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "created_at": "2026-10-27T08:54:22Z", "updated_at": "2026-10-27T08:54:23Z", "completed_at": null, "archived_at": null, "archived_by": null } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002/restore\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'" } ] } }, "/tasks/{task_id}/checklist": { "post": { "operationId": "addChecklistItem", "summary": "Adds a checklist item (at the end unless position is given)", "description": "Adds a checklist item (at the end unless position is given). 100 at most.", "tags": [ "Tasks" ], "x-capability": "tasks:write", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 500, "description": "max 500" }, "position": { "type": "integer", "description": "0 to 1000000" }, "done": { "type": "boolean", "description": "default false" } }, "required": [ "text" ] }, "example": { "text": "Check the VAT line" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "2a3b4c5d-0000-4000-8000-000000000008", "task_id": "7c1d2e3f-0000-4000-8000-000000000002", "text": "Check the VAT line", "done": false, "done_by": null, "done_at": null, "position": 0, "created_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "created_at": "2026-10-28T08:00:00Z", "updated_at": "2026-10-28T09:00:00Z" } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002/checklist\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"text\": \"Check the VAT line\"}'" } ] } }, "/tasks/{task_id}/checklist/{item_id}": { "patch": { "operationId": "updateChecklistItem", "summary": "Ticks or unticks (done), renames (text) or moves (position) an item", "description": "Ticks or unticks (done), renames (text) or moves (position) an item. POST works too.", "tags": [ "Tasks" ], "x-capability": "tasks:write", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 500, "description": "max 500" }, "done": { "type": "boolean" }, "position": { "type": "integer", "description": "0 to 1000000" } } }, "example": { "done": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "2a3b4c5d-0000-4000-8000-000000000008", "task_id": "7c1d2e3f-0000-4000-8000-000000000002", "text": "Check the VAT line", "done": true, "done_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "done_at": "2026-10-28T09:00:00Z", "position": 0, "created_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "created_at": "2026-10-28T08:00:00Z", "updated_at": "2026-10-28T09:00:00Z" } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X PATCH \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002/checklist/2a3b4c5d-0000-4000-8000-000000000008\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"done\": true}'" } ] }, "delete": { "operationId": "deleteChecklistItem", "summary": "Removes a checklist item", "description": "Removes a checklist item.", "tags": [ "Tasks" ], "x-capability": "tasks:write", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "2a3b4c5d-0000-4000-8000-000000000008", "task_id": "7c1d2e3f-0000-4000-8000-000000000002", "deleted": true } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X DELETE \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002/checklist/2a3b4c5d-0000-4000-8000-000000000008\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] } }, "/tasks/{task_id}/docs": { "post": { "operationId": "attachTaskDoc", "summary": "Links a Base doc of the group to the task (ids from GET /docs?source=base)", "description": "Links a Base doc of the group to the task (ids from GET /docs?source=base). No effect if already linked.", "tags": [ "Tasks" ], "x-capability": "tasks:write", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "doc_id": { "type": "string", "format": "uuid", "description": "a Base doc of the group" } }, "required": [ "doc_id" ] }, "example": { "doc_id": "6d7e8f90-0000-4000-8000-000000000006" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "task_id": "7c1d2e3f-0000-4000-8000-000000000002", "doc_id": "6d7e8f90-0000-4000-8000-000000000006", "attached": true, "already": false } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002/docs\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"doc_id\": \"6d7e8f90-0000-4000-8000-000000000006\"}'" } ] } }, "/tasks/{task_id}/docs/{doc_id}": { "delete": { "operationId": "detachTaskDoc", "summary": "Removes the link between the doc and the task (the doc stays)", "description": "Removes the link between the doc and the task (the doc stays).", "tags": [ "Tasks" ], "x-capability": "tasks:write", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "doc_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "task_id": "7c1d2e3f-0000-4000-8000-000000000002", "doc_id": "6d7e8f90-0000-4000-8000-000000000006", "attached": false } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X DELETE \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002/docs/6d7e8f90-0000-4000-8000-000000000006\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] } }, "/tasks/{task_id}/comments/{comment_id}": { "delete": { "operationId": "deleteTaskComment", "summary": "Deletes one of the agent's own comments (never a member's: 404)", "description": "Deletes one of the agent's own comments (never a member's: 404).", "tags": [ "Tasks" ], "x-capability": "tasks:write", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "5b6c7d8e-0000-4000-8000-000000000005", "task_id": "7c1d2e3f-0000-4000-8000-000000000002", "deleted": true } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X DELETE \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002/comments/5b6c7d8e-0000-4000-8000-000000000005\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] } }, "/tasks/{task_id}/status": { "post": { "operationId": "setTaskStatus", "summary": "Changes the status (a PATCH shortcut)", "description": "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.", "tags": [ "Tasks" ], "x-capability": "tasks:write", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "todo", "in_progress", "to_check", "done", "on_hold" ], "description": "todo | in_progress | to_check | done | on_hold" } }, "required": [ "status" ] }, "example": { "status": "done" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "7c1d2e3f-0000-4000-8000-000000000002", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "project_id": "9a8b7c6d-0000-4000-8000-000000000003", "title": "Prepare the October invoice", "description": null, "status": "todo", "priority": "high", "is_incontournable": true, "assignee_ids": [ "agent_5f2a9c0e1d3b4a6f7e8d9c0b" ], "assigned_to_all": false, "due_at": "2026-10-30T15:00:00+00:00", "due_date": "2026-10-30T00:00:00+00:00", "start_at": "2026-10-27T23:00:00+00:00", "reminder_offset_minutes": 60, "alarm": false, "recurrence": { "type": "monthly", "days": null, "end_date": "2027-04-30", "month_day": 30 }, "series_id": "7c1d2e3f-0000-4000-8000-000000000002", "occurrence_date": "2026-10-30", "hold_until_date": null, "blocked_by_task_id": null, "blocked_by_status": null, "topic_id": null, "folder_id": null, "follows_task_id": null, "parent_task_id": null, "review_type": "none", "reviewer_ids": [], "position": 0, "origin_kind": null, "created_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "created_at": "2026-10-27T08:54:22Z", "updated_at": "2026-10-27T08:54:23Z", "completed_at": null, "archived_at": null, "archived_by": null } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002/status\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"status\": \"done\"}'" } ] } }, "/tasks/{task_id}/assignees": { "post": { "operationId": "assignTask", "summary": "Replaces the assignees (human members; an empty list clears it)", "description": "Replaces the assignees (human members; an empty list clears it). The agent keeps its own assignment.", "tags": [ "Tasks" ], "x-capability": "tasks:write", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assignee_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "description": "member ids, max 50" } }, "required": [ "assignee_ids" ] }, "example": { "assignee_ids": [ "user_2abcDEFghiJKLmnoPQRstu" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "7c1d2e3f-0000-4000-8000-000000000002", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "project_id": "9a8b7c6d-0000-4000-8000-000000000003", "title": "Prepare the October invoice", "description": null, "status": "todo", "priority": "high", "is_incontournable": true, "assignee_ids": [ "agent_5f2a9c0e1d3b4a6f7e8d9c0b" ], "assigned_to_all": false, "due_at": "2026-10-30T15:00:00+00:00", "due_date": "2026-10-30T00:00:00+00:00", "start_at": "2026-10-27T23:00:00+00:00", "reminder_offset_minutes": 60, "alarm": false, "recurrence": { "type": "monthly", "days": null, "end_date": "2027-04-30", "month_day": 30 }, "series_id": "7c1d2e3f-0000-4000-8000-000000000002", "occurrence_date": "2026-10-30", "hold_until_date": null, "blocked_by_task_id": null, "blocked_by_status": null, "topic_id": null, "folder_id": null, "follows_task_id": null, "parent_task_id": null, "review_type": "none", "reviewer_ids": [], "position": 0, "origin_kind": null, "created_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "created_at": "2026-10-27T08:54:22Z", "updated_at": "2026-10-27T08:54:23Z", "completed_at": null, "archived_at": null, "archived_by": null } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002/assignees\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"assignee_ids\": [\"user_2abcDEFghiJKLmnoPQRstu\"]}'" } ] } }, "/tasks/{task_id}/comments": { "post": { "operationId": "commentTask", "summary": "Adds a comment (max 4000 characters)", "description": "Adds a comment (max 4000 characters).", "tags": [ "Tasks" ], "x-capability": "tasks:write", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 4000, "description": "max 4000" } }, "required": [ "content" ] }, "example": { "content": "Done, numbers are in the sheet." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "5b6c7d8e-0000-4000-8000-000000000005", "task_id": "7c1d2e3f-0000-4000-8000-000000000002", "created_at": "2026-10-27T10:00:00Z" } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002/comments\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Done, numbers are in the sheet.\"}'" } ] } }, "/tasks/{task_id}/take": { "post": { "operationId": "takeTask", "summary": "The agent assigns itself (others stay)", "description": "The agent assigns itself (others stay). 409 task_for_everyone on an \"everyone\" task.", "tags": [ "Tasks" ], "x-capability": "tasks:self_assign", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "7c1d2e3f-0000-4000-8000-000000000002", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "project_id": "9a8b7c6d-0000-4000-8000-000000000003", "title": "Prepare the October invoice", "description": null, "status": "todo", "priority": "high", "is_incontournable": true, "assignee_ids": [ "agent_5f2a9c0e1d3b4a6f7e8d9c0b" ], "assigned_to_all": false, "due_at": "2026-10-30T15:00:00+00:00", "due_date": "2026-10-30T00:00:00+00:00", "start_at": "2026-10-27T23:00:00+00:00", "reminder_offset_minutes": 60, "alarm": false, "recurrence": { "type": "monthly", "days": null, "end_date": "2027-04-30", "month_day": 30 }, "series_id": "7c1d2e3f-0000-4000-8000-000000000002", "occurrence_date": "2026-10-30", "hold_until_date": null, "blocked_by_task_id": null, "blocked_by_status": null, "topic_id": null, "folder_id": null, "follows_task_id": null, "parent_task_id": null, "review_type": "none", "reviewer_ids": [], "position": 0, "origin_kind": null, "created_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "created_at": "2026-10-27T08:54:22Z", "updated_at": "2026-10-27T08:54:23Z", "completed_at": null, "archived_at": null, "archived_by": null } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002/take\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'" } ] } }, "/tasks/{task_id}/release": { "post": { "operationId": "releaseTask", "summary": "The agent takes itself off the task", "description": "The agent takes itself off the task.", "tags": [ "Tasks" ], "x-capability": "tasks:self_assign", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "7c1d2e3f-0000-4000-8000-000000000002", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "project_id": "9a8b7c6d-0000-4000-8000-000000000003", "title": "Prepare the October invoice", "description": null, "status": "todo", "priority": "high", "is_incontournable": true, "assignee_ids": [ "agent_5f2a9c0e1d3b4a6f7e8d9c0b" ], "assigned_to_all": false, "due_at": "2026-10-30T15:00:00+00:00", "due_date": "2026-10-30T00:00:00+00:00", "start_at": "2026-10-27T23:00:00+00:00", "reminder_offset_minutes": 60, "alarm": false, "recurrence": { "type": "monthly", "days": null, "end_date": "2027-04-30", "month_day": 30 }, "series_id": "7c1d2e3f-0000-4000-8000-000000000002", "occurrence_date": "2026-10-30", "hold_until_date": null, "blocked_by_task_id": null, "blocked_by_status": null, "topic_id": null, "folder_id": null, "follows_task_id": null, "parent_task_id": null, "review_type": "none", "reviewer_ids": [], "position": 0, "origin_kind": null, "created_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "created_at": "2026-10-27T08:54:22Z", "updated_at": "2026-10-27T08:54:23Z", "completed_at": null, "archived_at": null, "archived_by": null } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002/release\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'" } ] } }, "/tasks/{task_id}/project": { "post": { "operationId": "setTaskProject", "summary": "Puts the task in a project, or takes it out with null", "description": "Puts the task in a project, or takes it out with null. A sub-task follows its parent (400 invalid_input).", "tags": [ "Projects" ], "x-capability": "tasks:write", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "a live project of the group, or null" } }, "required": [ "project_id" ] }, "example": { "project_id": "9a8b7c6d-0000-4000-8000-000000000003" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "7c1d2e3f-0000-4000-8000-000000000002", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "project_id": "9a8b7c6d-0000-4000-8000-000000000003", "title": "Prepare the October invoice", "description": null, "status": "todo", "priority": "high", "is_incontournable": true, "assignee_ids": [ "agent_5f2a9c0e1d3b4a6f7e8d9c0b" ], "assigned_to_all": false, "due_at": "2026-10-30T15:00:00+00:00", "due_date": "2026-10-30T00:00:00+00:00", "start_at": "2026-10-27T23:00:00+00:00", "reminder_offset_minutes": 60, "alarm": false, "recurrence": { "type": "monthly", "days": null, "end_date": "2027-04-30", "month_day": 30 }, "series_id": "7c1d2e3f-0000-4000-8000-000000000002", "occurrence_date": "2026-10-30", "hold_until_date": null, "blocked_by_task_id": null, "blocked_by_status": null, "topic_id": null, "folder_id": null, "follows_task_id": null, "parent_task_id": null, "review_type": "none", "reviewer_ids": [], "position": 0, "origin_kind": null, "created_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "created_at": "2026-10-27T08:54:22Z", "updated_at": "2026-10-27T08:54:23Z", "completed_at": null, "archived_at": null, "archived_by": null } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/tasks/7c1d2e3f-0000-4000-8000-000000000002/project\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"project_id\": \"9a8b7c6d-0000-4000-8000-000000000003\"}'" } ] } }, "/projects": { "get": { "operationId": "listProjects", "summary": "Group projects (the app's \"projects\"): name, description, dates, status, task counts", "description": "Group projects (the app's \"projects\"): name, description, dates, status, task counts.", "tags": [ "Projects" ], "x-capability": "tasks:read", "parameters": [ { "name": "include_archived", "in": "query", "required": false, "description": "Also list archived projects.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": [ { "id": "9a8b7c6d-0000-4000-8000-000000000003", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "name": "Q4 launch", "description": "Ship the web app before December.", "start_date": "2026-11-01", "end_date": "2026-11-30", "status": "active", "position": 0, "task_count": 12, "done_count": 5, "created_by": "user_2abcDEFghiJKLmnoPQRstu", "created_at": "2026-10-20T09:00:00Z", "updated_at": "2026-10-20T09:00:00Z" } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s \"$WHATNXT_BASE/projects\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] }, "post": { "operationId": "createProject", "summary": "Creates a project in the group", "description": "Creates a project in the group. Dates are YYYY-MM-DD, start not after end. 50 live projects per group (409 project_limit).", "tags": [ "Projects" ], "x-capability": "tasks:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120, "description": "max 120" }, "description": { "type": "string", "maxLength": 10000, "description": "max 2000" }, "start_date": { "type": "string", "format": "date", "description": "YYYY-MM-DD" }, "end_date": { "type": "string", "format": "date", "description": "YYYY-MM-DD" } }, "required": [ "name" ] }, "example": { "name": "Q4 launch", "description": "Ship the web app before December.", "start_date": "2026-11-01", "end_date": "2026-11-30" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "9a8b7c6d-0000-4000-8000-000000000003", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "name": "Q4 launch", "description": "Ship the web app before December.", "start_date": "2026-11-01", "end_date": "2026-11-30", "status": "active", "position": 0, "task_count": 0, "done_count": 0, "created_by": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "created_at": "2026-10-20T09:00:00Z", "updated_at": "2026-10-20T09:00:00Z" } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/projects\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"Q4 launch\", \"description\": \"Ship the web app before December.\", \"start_date\": \"2026-11-01\", \"end_date\": \"2026-11-30\"}'" } ] } }, "/messages": { "get": { "operationId": "listMessages", "summary": "The group chat or one thread, oldest first", "description": "The group chat or one thread, oldest first. Never private side chats. From when the agent joined, unless the admin opened the full history.", "tags": [ "Messages and notifications" ], "x-capability": "messages:read", "parameters": [ { "name": "thread_id", "in": "query", "required": false, "description": "One thread only.", "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "required": false, "description": "Messages before this time (paging).", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "1 to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": [ { "id": "3e4f5a6b-0000-4000-8000-000000000004", "author_id": "user_2abcDEFghiJKLmnoPQRstu", "author_name": "Jey", "author_kind": "user", "content": "Invoices are due Friday.", "created_at": "2026-10-27T09:00:00Z", "edited_at": null, "reply_to_id": null, "thread_id": null, "media": null } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s \"$WHATNXT_BASE/messages?limit=20\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] }, "post": { "operationId": "postMessage", "summary": "Posts in the group chat (max 4000)", "description": "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.", "tags": [ "Messages and notifications" ], "x-capability": "messages:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 4000, "description": "max 4000" }, "reply_to_id": { "type": "string", "format": "uuid" } }, "required": [ "content" ] }, "example": { "content": "Invoice ready, @Jey can you check it?" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "3e4f5a6b-0000-4000-8000-000000000004", "thread_id": null, "created_at": "2026-10-27T10:02:00Z" } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/messages\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Invoice ready, @Jey can you check it?\"}'" } ] } }, "/notify": { "post": { "operationId": "notifyOwner", "summary": "One push notification to the agent's owner (max 200 characters)", "description": "One push notification to the agent's owner (max 200 characters). Nothing is stored. Skipped in Do Not Disturb.", "tags": [ "Messages and notifications" ], "x-capability": "notify:owner", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 500, "description": "max 200" } }, "required": [ "text" ] }, "example": { "text": "Build finished" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "sent": 1 } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/notify\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"text\": \"Build finished\"}'" } ] } }, "/typing": { "post": { "operationId": "setTyping", "summary": "Shows \" is typing\" in the group for 20 s", "description": "Shows \" is typing\" in the group for 20 s. Send it every 10 s while working; {\"state\":\"off\"} stops it.", "tags": [ "Messages and notifications" ], "x-capability": null, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "description": "\"off\" to stop, anything else starts" } } }, "example": { "state": "on" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "typing": true } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/typing\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"state\": \"on\"}'" } ] } }, "/mentions": { "get": { "operationId": "listMentions", "summary": "Messages that mention the agent (@Name), oldest first, max 50", "description": "Messages that mention the agent (@Name), oldest first, max 50. The text only when the agent has messages:read.", "tags": [ "Mentions" ], "x-capability": null, "parameters": [ { "name": "after", "in": "query", "required": false, "description": "Cursor: ids after this one. Default: the stored read cursor.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "1 to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "items": [ { "id": 42, "agent_id": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "message_id": "3e4f5a6b-0000-4000-8000-000000000004", "thread_id": null, "reply_to_id": null, "author_id": "user_2abcDEFghiJKLmnoPQRstu", "created_at": "2026-10-27T09:12:00Z", "text": "@Finance can you sum up the open invoices?" } ], "cursor": 42, "read_upto": 41 } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s \"$WHATNXT_BASE/mentions\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] } }, "/mentions/wait": { "get": { "operationId": "waitForMentions", "summary": "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", "description": "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).", "tags": [ "Mentions" ], "x-capability": null, "parameters": [ { "name": "after", "in": "query", "required": false, "description": "Cursor.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "1 to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "timeout", "in": "query", "required": false, "description": "Seconds, 1 to 55, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 55 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "items": [ { "id": 42, "agent_id": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "group_id": "1f5e2e03-0000-4000-8000-000000000001", "message_id": "3e4f5a6b-0000-4000-8000-000000000004", "thread_id": null, "reply_to_id": null, "author_id": "user_2abcDEFghiJKLmnoPQRstu", "created_at": "2026-10-27T09:12:00Z", "text": "@Finance can you sum up the open invoices?" } ], "cursor": 42, "read_upto": 41 } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s \"$WHATNXT_BASE/mentions/wait?timeout=50\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] } }, "/mentions/read": { "post": { "operationId": "markMentionsRead", "summary": "Moves the read cursor forward (never back)", "description": "Moves the read cursor forward (never back).", "tags": [ "Mentions" ], "x-capability": null, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "up_to": { "type": "integer", "description": "a mention id" } }, "required": [ "up_to" ] }, "example": { "up_to": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "read_upto": 42 } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/mentions/read\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"up_to\": 42}'" } ] } }, "/docs": { "get": { "operationId": "listDocs", "summary": "Base docs and group-chat files, newest first", "description": "Base docs and group-chat files, newest first.", "tags": [ "Files" ], "x-capability": "docs:read", "parameters": [ { "name": "source", "in": "query", "required": false, "description": "base or chat.", "schema": { "type": "string", "enum": [ "base", "chat" ] } }, { "name": "before", "in": "query", "required": false, "description": "Paging.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "1 to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "items": [ { "source": "base", "id": "6d7e8f90-0000-4000-8000-000000000006", "title": "Budget 2027", "file_name": "budget.xlsx", "file_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "file_size": 48213, "has_file": true, "has_text": false, "author_id": "user_2abcDEFghiJKLmnoPQRstu", "author_name": "Jey", "created_at": "2026-10-20T08:00:00Z", "updated_at": "2026-10-20T08:00:00Z" } ] } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s \"$WHATNXT_BASE/docs\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] } }, "/docs/{source}/{id}": { "get": { "operationId": "getDoc", "summary": "One doc: its metadata, the text of a Base text doc (first 200,000 characters) and download_url, a signed link valid 5 minutes", "description": "One doc: its metadata, the text of a Base text doc (first 200,000 characters) and download_url, a signed link valid 5 minutes.", "tags": [ "Files" ], "x-capability": "docs:read", "parameters": [ { "name": "source", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "base", "chat" ] } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "source": "base", "id": "6d7e8f90-0000-4000-8000-000000000006", "title": "Budget 2027", "file_name": "budget.xlsx", "file_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "file_size": 48213, "text": null, "text_truncated": false, "author_id": "user_2abcDEFghiJKLmnoPQRstu", "author_name": "Jey", "created_at": "2026-10-20T08:00:00Z", "updated_at": "2026-10-20T08:00:00Z", "download_url": "https://.../storage/v1/object/sign/Docs/...", "download_expires_in": 300 } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s \"$WHATNXT_BASE/docs/base/6d7e8f90-0000-4000-8000-000000000006\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] } }, "/files": { "post": { "operationId": "getUploadUrl", "summary": "Reserves an upload: returns path and upload_url", "description": "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.", "tags": [ "Files" ], "x-capability": "files:post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_name": { "type": "string", "maxLength": 200, "description": "max 200" }, "size": { "type": "integer", "description": "bytes, max 20971520" } }, "required": [ "file_name", "size" ] }, "example": { "file_name": "report.pdf", "size": 182044 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "path": "1f5e2e03-0000-4000-8000-000000000001/agent-...-report.pdf", "upload_url": "https://.../storage/v1/object/upload/sign/Docs/...", "method": "PUT", "max_bytes": 20971520 } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/files\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"file_name\": \"report.pdf\", \"size\": 182044}'" } ] } }, "/messages/file": { "post": { "operationId": "postFile", "summary": "Sends a file in the chat: either path (after POST /v1/files) or content_base64 (standard base64, no data: prefix)", "description": "Sends a file in the chat: either path (after POST /v1/files) or content_base64 (standard base64, no data: prefix).", "tags": [ "Files" ], "x-capability": "files:post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "description": "from POST /v1/files" }, "content_base64": { "type": "string", "description": "exactly one of path or content_base64" }, "file_name": { "type": "string", "maxLength": 200, "description": "max 200" }, "file_type": { "type": "string", "description": "MIME type, default application/octet-stream" }, "caption": { "type": "string", "maxLength": 4000, "description": "max 4000" }, "reply_to_id": { "type": "string", "format": "uuid" } }, "required": [ "file_name" ] }, "example": { "content_base64": "SGVsbG8gV2hhdE54dAo=", "file_name": "hello.txt", "file_type": "text/plain" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "id": "3e4f5a6b-0000-4000-8000-000000000004", "thread_id": null, "created_at": "2026-10-27T10:05:00Z", "file_name": "hello.txt", "file_size": 15, "file_type": "text/plain" } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/messages/file\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content_base64\": \"SGVsbG8gV2hhdE54dAo=\", \"file_name\": \"hello.txt\", \"file_type\": \"text/plain\"}'" } ] } }, "/capabilities/request": { "post": { "operationId": "requestCapabilities", "summary": "Asks the group admins for more rights (they get a push)", "description": "Asks the group admins for more rights (they get a push). Only rights the owner gave the agent. 3 requests an hour.", "tags": [ "Rights, rules and approvals" ], "x-capability": null, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "description": "group capabilities" } }, "required": [ "capabilities" ] }, "example": { "capabilities": [ "messages:read" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "requested": [ "messages:read" ], "pending": [ "messages:read" ] } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/capabilities/request\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"capabilities\": [\"messages:read\"]}'" } ] } }, "/rules": { "get": { "operationId": "getRules", "summary": "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", "description": "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.", "tags": [ "Rights, rules and approvals" ], "x-capability": null, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "machine": { "read": "yes", "write": "ask", "delete": "no", "send": "no", "commands": "no", "internet": "no" }, "machine_set": true, "instructions": "", "writers": "everyone", "writer_ids": [], "hours": { "on": false, "days": [ 1, 2, 3, 4, 5 ], "start_min": 480, "end_min": 1140, "timezone": "Europe/Zurich", "hold": true }, "in_hours": true, "limits": { "messages_per_hour": null, "files_per_hour": null }, "approved": [], "agent_id": "agent_5f2a9c0e1d3b4a6f7e8d9c0b", "project_id": "1f5e2e03-0000-4000-8000-000000000001", "updated_at": "2026-10-17T18:14:35Z" } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s \"$WHATNXT_BASE/rules\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] } }, "/approvals": { "post": { "operationId": "requestApproval", "summary": "For an action set to \"ask\": posts an Approve / Refuse card only the owner can answer", "description": "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.", "tags": [ "Rights, rules and approvals" ], "x-capability": "messages:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "read", "write", "delete", "send", "commands", "internet" ], "description": "read | write | delete | send | commands | internet" }, "summary": { "type": "string", "maxLength": 300, "description": "max 300" }, "reply_to_id": { "type": "string", "format": "uuid" } }, "required": [ "category", "summary" ] }, "example": { "category": "write", "summary": "Write the October report to reports/2026-10.md" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "approval_id": "8f9e0d1c-0000-4000-8000-000000000007", "category": "write", "status": "pending", "expires_at": "2026-10-27T11:00:00Z", "message_id": "3e4f5a6b-0000-4000-8000-000000000004", "needed": true } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s -X POST \"$WHATNXT_BASE/approvals\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"category\": \"write\", \"summary\": \"Write the October report to reports/2026-10.md\"}'" } ] } }, "/approvals/{approval_id}": { "get": { "operationId": "getApproval", "summary": "A card's state: pending, approved, refused or expired", "description": "A card's state: pending, approved, refused or expired. Waits while pending (timeout default 45 s, 0 = at once, max 55).", "tags": [ "Rights, rules and approvals" ], "x-capability": null, "parameters": [ { "name": "approval_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "timeout", "in": "query", "required": false, "description": "Seconds, 0 to 55.", "schema": { "type": "integer", "minimum": 0, "maximum": 55 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Data" }, "example": { "data": { "approval_id": "8f9e0d1c-0000-4000-8000-000000000007", "category": "write", "status": "approved", "expires_at": "2026-10-27T11:00:00Z", "decided_at": "2026-10-27T10:20:00Z", "valid_until": "2026-10-27T10:30:00Z", "used": false } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "export WHATNXT_BASE=\"https://oijlvvqvwhqyjemmuegz.supabase.co/functions/v1/agent-api/v1\"\ncurl -s \"$WHATNXT_BASE/approvals/8f9e0d1c-0000-4000-8000-000000000007\" \\\n -H \"Authorization: Bearer $WHATNXT_KEY\"" } ] } }, "/": { "get": { "operationId": "apiIndex", "summary": "API index (no key)", "security": [], "tags": [ "Identity and group" ], "description": "The bare base answers where the docs are. No key needed, no data.", "responses": { "200": { "description": "Index", "content": { "application/json": { "example": { "name": "WhatNxt Agents API", "version": "v1", "docs": "https://whatnxt.dev/developers", "openapi": "https://whatnxt.dev/openapi.json", "llms": "https://whatnxt.dev/llms.txt", "auth": "Authorization: Bearer wnk_live_...", "start": "GET /v1/me", "note": "WhatNxt (whatnxt.dev) has no link with whatnxt.io." } } } } } } } }, "components": { "securitySchemes": { "agentKey": { "type": "http", "scheme": "bearer", "bearerFormat": "wnk_live_ + 43 base64url characters", "description": "The agent key, created by the agent owner in the WhatNxt app (Profile, Agents and API)." } }, "schemas": { "Data": { "type": "object", "required": [ "data" ], "properties": { "data": {} } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_key", "agents_disabled", "capability_missing", "capability_not_granted", "agent_pending", "rule_forbidden", "invalid_input", "not_a_member", "invalid_capability", "not_found", "unknown_route", "method_not_allowed", "delete_not_allowed", "review_required", "task_for_everyone", "task_archived", "wait_superseded", "project_limit", "payload_too_large", "rate_limited", "write_limit", "message_cap", "rule_limit", "internal_error" ] }, "field": { "type": "string", "description": "The input field at fault (invalid_input, not_a_member, not_found on a body id)." }, "docs": { "type": "string", "format": "uri" }, "hint": { "type": "string" } } } }, "responses": { "Error": { "description": "Error. HTTP status by code: invalid_key 401, agents_disabled 403, capability_missing 403, capability_not_granted 403, agent_pending 403, rule_forbidden 403, invalid_input 400, not_a_member 400, invalid_capability 400, not_found 404, unknown_route 404, method_not_allowed 405, delete_not_allowed 405, review_required 409, task_for_everyone 409, task_archived 409, wait_superseded 409, project_limit 409, payload_too_large 413, rate_limited 429, write_limit 429, message_cap 429, rule_limit 429, internal_error 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "capability_missing", "docs": "https://whatnxt.dev/developers" } } } } } } }