{ "specVersion": "3.0.3", "specFormat": "openapi", "specFile": "openapi.yaml", "installSpecPath": null, "title": "Next Task REST API", "summary": "Read and change lists and tasks on Joomla's Web Services application.", "description": "Lists and tasks over Joomla's Web Services application, authenticated with Joomla's\nstandard API token. A call acts as the token's user: it sees and changes exactly what\nthat user can in the app, and what their roles allow applies here too.\n\nEvery answer from Next Task is JSON in the same envelope, `success`, `data` and\n`message`, with a real HTTP status. Due dates are written in the site's time zone,\nwithout a zone suffix.\n", "apiVersion": "1.0.0", "license": { "name": "GNU General Public License v2.0 or later", "url": "https://www.gnu.org/licenses/old-licenses/gpl-2.0.html" }, "contact": { "name": "NextSoftware", "url": "https://nextsoftware.dev/", "email": "support@nextsoftware.dev" }, "style": "rest-path", "guide": "rest-api/getting-started", "navSection": "api", "navEventsSection": "", "baseUrl": { "template": "{protocol}://{host}{basePath}/api/index.php", "variables": { "protocol": { "description": "Use http only for local development.", "example": "https", "enum": [ "https", "http" ] }, "host": { "description": "The host your Joomla site runs on.", "example": "your-site.example", "enum": null }, "basePath": { "description": "Empty when Joomla is installed at the domain root. Otherwise the subfolder it is installed in, with a leading slash and no trailing slash.", "example": "", "enum": null } }, "example": "https://your-site.example/api/index.php" }, "auth": { "type": "header", "header": "X-Joomla-Token", "scheme": null, "queryParam": null, "example": "X-Joomla-Token: ", "alternatives": [], "enablement": [], "notes": [ "The token from the user's Joomla API Token tab." ] }, "conventions": [], "groups": [ { "id": "Lists", "title": "Lists", "description": "Personal lists and the lists shared with the token's user." }, { "id": "Tasks", "title": "Tasks", "description": "Tasks and subtasks, one at a time or several at once." } ], "endpoints": [ { "id": "listLists", "slug": "lists", "pagePath": "api/lists", "group": "Lists", "method": "GET", "operation": "/v1/nexttask/lists", "summary": "List your lists", "title": "List Lists", "description": "Your own lists and the lists shared with you.", "stability": "stable", "deprecated": null, "auth": true, "params": [], "requestBody": null, "responses": [ { "status": 200, "description": "The lists.", "example": { "success": true, "message": "string", "messages": "string", "data": { "items": [ { "id": 5, "user_id": 1, "title": "Groceries", "color": "#1967d2", "position": "string", "is_default": 1, "is_team": 1, "owner_name": "string", "access": "owner", "can_leave": true, "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 } ] } }, "fields": [], "notes": "" } ], "errors": [ "http_401" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s \"https://your-site.example/api/index.php/v1/nexttask/lists\" \\\n -H \"X-Joomla-Token: $API_TOKEN\"" } ], "sections": [], "seoTitle": "List your lists", "seoDescription": "GET /v1/nexttask/lists returns your own lists and the lists shared with you.", "seoKeywords": null }, { "id": "createList", "slug": "post-lists", "pagePath": "api/post-lists", "group": "Lists", "method": "POST", "operation": "/v1/nexttask/lists", "summary": "Create a list", "title": "Create List", "description": "Needs **Lists > Create**.", "stability": "stable", "deprecated": null, "auth": true, "params": [], "requestBody": { "contentType": "application/json", "required": true, "description": "", "fields": [ { "name": "title", "type": "string", "required": false, "description": "", "enum": null, "default": null, "children": [] }, { "name": "color", "type": "string", "required": false, "description": "A hex colour.", "enum": null, "default": null, "children": [] } ], "example": { "title": "Groceries", "color": "#1967d2" } }, "responses": [ { "status": 200, "description": "The list.", "example": { "success": true, "message": "string", "messages": "string", "data": { "item": { "id": 5, "user_id": 1, "title": "Groceries", "color": "#1967d2", "position": "string", "is_default": 1, "is_team": 1, "owner_name": "string", "access": "owner", "can_leave": true, "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 } } }, "fields": [], "notes": "" } ], "errors": [ "http_401", "http_403", "http_422" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s -X POST \"https://your-site.example/api/index.php/v1/nexttask/lists\" \\\n -H \"X-Joomla-Token: $API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"title\":\"Groceries\",\"color\":\"#1967d2\"}'" } ], "sections": [], "seoTitle": "Create a list", "seoDescription": "POST /v1/nexttask/lists creates a list with a title and colour. Needs the Lists > Create permission.", "seoKeywords": null }, { "id": "getList", "slug": "get-lists", "pagePath": "api/get-lists", "group": "Lists", "method": "GET", "operation": "/v1/nexttask/lists/{id}", "summary": "Get a list", "title": "Get List", "description": "One list you can reach.", "stability": "stable", "deprecated": null, "auth": true, "params": [ { "name": "id", "in": "path", "type": "integer", "required": true, "default": null, "enum": null, "example": null, "description": "The record the call is about. An `id` or `ids` in the body is ignored." } ], "requestBody": null, "responses": [ { "status": 200, "description": "The list.", "example": { "success": true, "message": "string", "messages": "string", "data": { "item": { "id": 5, "user_id": 1, "title": "Groceries", "color": "#1967d2", "position": "string", "is_default": 1, "is_team": 1, "owner_name": "string", "access": "owner", "can_leave": true, "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 } } }, "fields": [], "notes": "" } ], "errors": [ "http_401", "http_404" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s \"https://your-site.example/api/index.php/v1/nexttask/lists/1\" \\\n -H \"X-Joomla-Token: $API_TOKEN\"" } ], "sections": [], "seoTitle": "Get a list", "seoDescription": "GET /v1/nexttask/lists/{id} returns one list you can reach.", "seoKeywords": null }, { "id": "updateList", "slug": "patch-lists", "pagePath": "api/patch-lists", "group": "Lists", "method": "PATCH", "operation": "/v1/nexttask/lists/{id}", "summary": "Change a list", "title": "Update List", "description": "Changes only the fields sent. Needs **Lists > Edit**, on a list you own.", "stability": "stable", "deprecated": null, "auth": true, "params": [ { "name": "id", "in": "path", "type": "integer", "required": true, "default": null, "enum": null, "example": null, "description": "The record the call is about. An `id` or `ids` in the body is ignored." } ], "requestBody": { "contentType": "application/json", "required": true, "description": "", "fields": [ { "name": "title", "type": "string", "required": false, "description": "", "enum": null, "default": null, "children": [] }, { "name": "color", "type": "string", "required": false, "description": "A hex colour.", "enum": null, "default": null, "children": [] } ], "example": { "title": "Weekly groceries" } }, "responses": [ { "status": 200, "description": "The list.", "example": { "success": true, "message": "string", "messages": "string", "data": { "item": { "id": 5, "user_id": 1, "title": "Groceries", "color": "#1967d2", "position": "string", "is_default": 1, "is_team": 1, "owner_name": "string", "access": "owner", "can_leave": true, "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 } } }, "fields": [], "notes": "" } ], "errors": [ "http_401", "http_403", "http_404", "http_422" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s -X PATCH \"https://your-site.example/api/index.php/v1/nexttask/lists/1\" \\\n -H \"X-Joomla-Token: $API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"title\":\"Weekly groceries\"}'" } ], "sections": [], "seoTitle": "Change a list", "seoDescription": "PATCH /v1/nexttask/lists/{id} changes only the fields sent, on a list you own.", "seoKeywords": null }, { "id": "deleteList", "slug": "delete-lists", "pagePath": "api/delete-lists", "group": "Lists", "method": "DELETE", "operation": "/v1/nexttask/lists/{id}", "summary": "Delete a list", "title": "Delete List", "description": "Deletes a list you own and its tasks. Needs **Lists > Delete**. A default list cannot be deleted.", "stability": "stable", "deprecated": null, "auth": true, "params": [ { "name": "id", "in": "path", "type": "integer", "required": true, "default": null, "enum": null, "example": null, "description": "The record the call is about. An `id` or `ids` in the body is ignored." } ], "requestBody": null, "responses": [ { "status": 200, "description": "The ids deleted.", "example": { "success": true, "message": "string", "messages": "string", "data": { "deleted": [ 1 ] } }, "fields": [], "notes": "" } ], "errors": [ "http_401", "http_403", "http_404" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s -X DELETE \"https://your-site.example/api/index.php/v1/nexttask/lists/1\" \\\n -H \"X-Joomla-Token: $API_TOKEN\"" } ], "sections": [], "seoTitle": "Delete a list", "seoDescription": "DELETE /v1/nexttask/lists/{id} deletes a list you own and its tasks.", "seoKeywords": null }, { "id": "getListMembers", "slug": "lists-members", "pagePath": "api/lists-members", "group": "Lists", "method": "GET", "operation": "/v1/nexttask/lists/{id}/members", "summary": "List a list's members", "title": "Get List Members", "description": "Everyone who can reach the list, which is who its tasks can be assigned to.", "stability": "stable", "deprecated": null, "auth": true, "params": [ { "name": "id", "in": "path", "type": "integer", "required": true, "default": null, "enum": null, "example": null, "description": "The record the call is about. An `id` or `ids` in the body is ignored." } ], "requestBody": null, "responses": [ { "status": 200, "description": "The members.", "example": { "success": true, "message": "string", "messages": "string", "data": { "items": [ { "id": 7, "name": "Maria Lopez", "username": "maria", "access": "owner" } ] } }, "fields": [], "notes": "" } ], "errors": [ "http_401", "http_404" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s \"https://your-site.example/api/index.php/v1/nexttask/lists/1/members\" \\\n -H \"X-Joomla-Token: $API_TOKEN\"" } ], "sections": [], "seoTitle": "List members", "seoDescription": "GET /v1/nexttask/lists/{id}/members returns everyone who can reach a list, who its tasks can be assigned to.", "seoKeywords": null }, { "id": "listTasks", "slug": "tasks", "pagePath": "api/tasks", "group": "Tasks", "method": "GET", "operation": "/v1/nexttask/tasks", "summary": "List tasks", "title": "List Tasks", "description": "Tasks you can reach, narrowed by the filters.", "stability": "stable", "deprecated": null, "auth": true, "params": [ { "name": "list_id", "in": "query", "type": "integer", "required": false, "default": null, "enum": null, "example": null, "description": "Only this list." }, { "name": "view", "in": "query", "type": "string", "required": false, "default": null, "enum": [ "starred", "today", "overdue", "assigned" ], "example": null, "description": "A smart view across your lists." }, { "name": "search", "in": "query", "type": "string", "required": false, "default": null, "enum": null, "example": null, "description": "Text to look for." }, { "name": "due_from", "in": "query", "type": "string", "required": false, "default": null, "enum": null, "example": null, "description": "Due on or after this date (YYYY-MM-DD). (date)" }, { "name": "due_to", "in": "query", "type": "string", "required": false, "default": null, "enum": null, "example": null, "description": "Due on or before this date (YYYY-MM-DD). (date)" }, { "name": "parent_id", "in": "query", "type": "integer", "required": false, "default": null, "enum": null, "example": null, "description": "Only the subtasks of this task." }, { "name": "limit", "in": "query", "type": "integer", "required": false, "default": null, "enum": null, "example": null, "description": "Page size." }, { "name": "offset", "in": "query", "type": "integer", "required": false, "default": null, "enum": null, "example": null, "description": "Rows to skip." } ], "requestBody": null, "responses": [ { "status": 200, "description": "The tasks.", "example": { "success": true, "message": "string", "messages": "string", "data": { "items": [ { "id": 12, "list_id": 5, "parent_id": 0, "title": "Ship it", "notes": "string", "status": "needsAction", "starred": 1, "due": "2026-10-02 09:00:00", "has_time": 1, "recurrence": "string", "recurrence_next_id": 1, "completed_time": "string", "position": "string", "links": [ {} ], "assigned_to": 1, "assignee_name": "string", "subtask_count": 1, "completed_subtask_count": 1, "access": "owner", "can_complete": true, "deleted_time": "string", "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 } ] } }, "fields": [], "notes": "" } ], "errors": [ "http_401" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s \"https://your-site.example/api/index.php/v1/nexttask/tasks\" \\\n -H \"X-Joomla-Token: $API_TOKEN\"" } ], "sections": [], "seoTitle": "List tasks", "seoDescription": "GET /v1/nexttask/tasks returns tasks, filtered by list, smart view, search, due dates or parent.", "seoKeywords": null }, { "id": "createTask", "slug": "post-tasks", "pagePath": "api/post-tasks", "group": "Tasks", "method": "POST", "operation": "/v1/nexttask/tasks", "summary": "Create a task", "title": "Create Task", "description": "Needs **Tasks > Create** and edit access to the list. Send `parent_id` to create a subtask.", "stability": "stable", "deprecated": null, "auth": true, "params": [], "requestBody": { "contentType": "application/json", "required": true, "description": "", "fields": [ { "name": "title", "type": "string", "required": false, "description": "", "enum": null, "default": null, "children": [] }, { "name": "list_id", "type": "integer", "required": false, "description": "", "enum": null, "default": null, "children": [] }, { "name": "parent_id", "type": "integer", "required": false, "description": "The parent task; 0 or empty for a top-level task.", "enum": null, "default": null, "children": [] }, { "name": "notes", "type": "string", "required": false, "description": "", "enum": null, "default": null, "children": [] }, { "name": "due", "type": "string", "required": false, "description": "YYYY-MM-DD HH:MM:SS in the site's time zone.", "enum": null, "default": null, "children": [] }, { "name": "has_time", "type": "integer", "required": false, "description": "1 when the time of `due` counts.", "enum": null, "default": null, "children": [] }, { "name": "starred", "type": "integer", "required": false, "description": "", "enum": null, "default": null, "children": [] }, { "name": "assigned_to", "type": "integer", "required": false, "description": "Someone who can reach the list; anyone else is refused with 422.", "enum": null, "default": null, "children": [] }, { "name": "links", "type": "object[]", "required": false, "description": "", "enum": null, "default": null, "children": [] } ], "example": { "title": "Ship it", "list_id": 5, "due": "2026-10-02 09:00:00", "has_time": 1 } }, "responses": [ { "status": 200, "description": "The task.", "example": { "success": true, "message": "string", "messages": "string", "data": { "item": { "id": 12, "list_id": 5, "parent_id": 0, "title": "Ship it", "notes": "string", "status": "needsAction", "starred": 1, "due": "2026-10-02 09:00:00", "has_time": 1, "recurrence": "string", "recurrence_next_id": 1, "completed_time": "string", "position": "string", "links": [ {} ], "assigned_to": 1, "assignee_name": "string", "subtask_count": 1, "completed_subtask_count": 1, "access": "owner", "can_complete": true, "deleted_time": "string", "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 } } }, "fields": [], "notes": "" } ], "errors": [ "http_401", "http_403", "http_422" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s -X POST \"https://your-site.example/api/index.php/v1/nexttask/tasks\" \\\n -H \"X-Joomla-Token: $API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"title\":\"Ship it\",\"list_id\":5,\"due\":\"2026-10-02 09:00:00\",\"has_time\":1}'" } ], "sections": [], "seoTitle": "Create a task", "seoDescription": "POST /v1/nexttask/tasks creates a task or subtask, with a due date, notes and an assignee.", "seoKeywords": null }, { "id": "bulkTasks", "slug": "tasks-bulk", "pagePath": "api/tasks-bulk", "group": "Tasks", "method": "POST", "operation": "/v1/nexttask/tasks/bulk", "summary": "Change several tasks", "title": "Bulk Tasks", "description": "Runs each change as its single-task call, with the same checks.", "stability": "stable", "deprecated": null, "auth": true, "params": [], "requestBody": { "contentType": "application/json", "required": true, "description": "", "fields": [ { "name": "ids", "type": "integer[]", "required": true, "description": "", "enum": null, "default": null, "children": [] }, { "name": "action", "type": "string", "required": true, "description": "", "enum": [ "complete", "reopen", "star", "unstar", "move", "assign", "delete" ], "default": null, "children": [] }, { "name": "list_id", "type": "integer", "required": false, "description": "Where to, for `move`.", "enum": null, "default": null, "children": [] }, { "name": "assigned_to", "type": "integer", "required": false, "description": "To whom, for `assign`.", "enum": null, "default": null, "children": [] } ], "example": { "ids": [ 3, 4 ], "action": "complete" } }, "responses": [ { "status": 200, "description": "The action, the tasks it changed and any next occurrences it created.", "example": { "success": true, "message": "string", "messages": "string", "data": { "action": "string", "ids": [ 1 ], "items": [ { "id": 12, "list_id": 5, "parent_id": 0, "title": "Ship it", "notes": "string", "status": "needsAction", "starred": 1, "due": "2026-10-02 09:00:00", "has_time": 1, "recurrence": "string", "recurrence_next_id": 1, "completed_time": "string", "position": "string", "links": [ {} ], "assigned_to": 1, "assignee_name": "string", "subtask_count": 1, "completed_subtask_count": 1, "access": "owner", "can_complete": true, "deleted_time": "string", "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 } ], "clones": [ { "id": 12, "list_id": 5, "parent_id": 0, "title": "Ship it", "notes": "string", "status": "needsAction", "starred": 1, "due": "2026-10-02 09:00:00", "has_time": 1, "recurrence": "string", "recurrence_next_id": 1, "completed_time": "string", "position": "string", "links": [ {} ], "assigned_to": 1, "assignee_name": "string", "subtask_count": 1, "completed_subtask_count": 1, "access": "owner", "can_complete": true, "deleted_time": "string", "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 } ] } }, "fields": [], "notes": "" } ], "errors": [ "http_401", "http_403", "http_422" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s -X POST \"https://your-site.example/api/index.php/v1/nexttask/tasks/bulk\" \\\n -H \"X-Joomla-Token: $API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[3,4],\"action\":\"complete\"}'" } ], "sections": [], "seoTitle": "Change several tasks", "seoDescription": "POST /v1/nexttask/tasks/bulk completes, reopens, stars, moves, assigns or deletes several tasks at once.", "seoKeywords": null }, { "id": "starTasks", "slug": "tasks-star", "pagePath": "api/tasks-star", "group": "Tasks", "method": "POST", "operation": "/v1/nexttask/tasks/star", "summary": "Star several tasks", "title": "Star Tasks", "description": "Stars the tasks, or unstars them with `starred` false. Answers as the bulk call does.", "stability": "stable", "deprecated": null, "auth": true, "params": [], "requestBody": { "contentType": "application/json", "required": true, "description": "", "fields": [ { "name": "ids", "type": "integer[]", "required": true, "description": "", "enum": null, "default": null, "children": [] }, { "name": "starred", "type": "boolean", "required": true, "description": "", "enum": null, "default": null, "children": [] } ], "example": { "ids": [ 3, 4 ], "starred": true } }, "responses": [ { "status": 200, "description": "The action, the tasks it changed and any next occurrences it created.", "example": { "success": true, "message": "string", "messages": "string", "data": { "action": "string", "ids": [ 1 ], "items": [ { "id": 12, "list_id": 5, "parent_id": 0, "title": "Ship it", "notes": "string", "status": "needsAction", "starred": 1, "due": "2026-10-02 09:00:00", "has_time": 1, "recurrence": "string", "recurrence_next_id": 1, "completed_time": "string", "position": "string", "links": [ {} ], "assigned_to": 1, "assignee_name": "string", "subtask_count": 1, "completed_subtask_count": 1, "access": "owner", "can_complete": true, "deleted_time": "string", "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 } ], "clones": [ { "id": 12, "list_id": 5, "parent_id": 0, "title": "Ship it", "notes": "string", "status": "needsAction", "starred": 1, "due": "2026-10-02 09:00:00", "has_time": 1, "recurrence": "string", "recurrence_next_id": 1, "completed_time": "string", "position": "string", "links": [ {} ], "assigned_to": 1, "assignee_name": "string", "subtask_count": 1, "completed_subtask_count": 1, "access": "owner", "can_complete": true, "deleted_time": "string", "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 } ] } }, "fields": [], "notes": "" } ], "errors": [ "http_401", "http_403", "http_422" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s -X POST \"https://your-site.example/api/index.php/v1/nexttask/tasks/star\" \\\n -H \"X-Joomla-Token: $API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[3,4],\"starred\":true}'" } ], "sections": [], "seoTitle": "Star several tasks", "seoDescription": "POST /v1/nexttask/tasks/star stars or unstars several tasks at once.", "seoKeywords": null }, { "id": "getTask", "slug": "get-tasks", "pagePath": "api/get-tasks", "group": "Tasks", "method": "GET", "operation": "/v1/nexttask/tasks/{id}", "summary": "Get a task", "title": "Get Task", "description": "One task you can reach.", "stability": "stable", "deprecated": null, "auth": true, "params": [ { "name": "id", "in": "path", "type": "integer", "required": true, "default": null, "enum": null, "example": null, "description": "The record the call is about. An `id` or `ids` in the body is ignored." } ], "requestBody": null, "responses": [ { "status": 200, "description": "The task.", "example": { "success": true, "message": "string", "messages": "string", "data": { "item": { "id": 12, "list_id": 5, "parent_id": 0, "title": "Ship it", "notes": "string", "status": "needsAction", "starred": 1, "due": "2026-10-02 09:00:00", "has_time": 1, "recurrence": "string", "recurrence_next_id": 1, "completed_time": "string", "position": "string", "links": [ {} ], "assigned_to": 1, "assignee_name": "string", "subtask_count": 1, "completed_subtask_count": 1, "access": "owner", "can_complete": true, "deleted_time": "string", "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 } } }, "fields": [], "notes": "" } ], "errors": [ "http_401", "http_404" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s \"https://your-site.example/api/index.php/v1/nexttask/tasks/1\" \\\n -H \"X-Joomla-Token: $API_TOKEN\"" } ], "sections": [], "seoTitle": "Get a task", "seoDescription": "GET /v1/nexttask/tasks/{id} returns one task you can reach.", "seoKeywords": null }, { "id": "updateTask", "slug": "patch-tasks", "pagePath": "api/patch-tasks", "group": "Tasks", "method": "PATCH", "operation": "/v1/nexttask/tasks/{id}", "summary": "Change a task", "title": "Update Task", "description": "Changes only the fields sent. Needs **Tasks > Edit** and edit access to its list.", "stability": "stable", "deprecated": null, "auth": true, "params": [ { "name": "id", "in": "path", "type": "integer", "required": true, "default": null, "enum": null, "example": null, "description": "The record the call is about. An `id` or `ids` in the body is ignored." } ], "requestBody": { "contentType": "application/json", "required": true, "description": "", "fields": [ { "name": "title", "type": "string", "required": false, "description": "", "enum": null, "default": null, "children": [] }, { "name": "list_id", "type": "integer", "required": false, "description": "", "enum": null, "default": null, "children": [] }, { "name": "parent_id", "type": "integer", "required": false, "description": "The parent task; 0 or empty for a top-level task.", "enum": null, "default": null, "children": [] }, { "name": "notes", "type": "string", "required": false, "description": "", "enum": null, "default": null, "children": [] }, { "name": "due", "type": "string", "required": false, "description": "YYYY-MM-DD HH:MM:SS in the site's time zone.", "enum": null, "default": null, "children": [] }, { "name": "has_time", "type": "integer", "required": false, "description": "1 when the time of `due` counts.", "enum": null, "default": null, "children": [] }, { "name": "starred", "type": "integer", "required": false, "description": "", "enum": null, "default": null, "children": [] }, { "name": "assigned_to", "type": "integer", "required": false, "description": "Someone who can reach the list; anyone else is refused with 422.", "enum": null, "default": null, "children": [] }, { "name": "links", "type": "object[]", "required": false, "description": "", "enum": null, "default": null, "children": [] } ], "example": { "notes": "Call before noon", "starred": 1 } }, "responses": [ { "status": 200, "description": "The task.", "example": { "success": true, "message": "string", "messages": "string", "data": { "item": { "id": 12, "list_id": 5, "parent_id": 0, "title": "Ship it", "notes": "string", "status": "needsAction", "starred": 1, "due": "2026-10-02 09:00:00", "has_time": 1, "recurrence": "string", "recurrence_next_id": 1, "completed_time": "string", "position": "string", "links": [ {} ], "assigned_to": 1, "assignee_name": "string", "subtask_count": 1, "completed_subtask_count": 1, "access": "owner", "can_complete": true, "deleted_time": "string", "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 } } }, "fields": [], "notes": "" } ], "errors": [ "http_401", "http_403", "http_404", "http_422" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s -X PATCH \"https://your-site.example/api/index.php/v1/nexttask/tasks/1\" \\\n -H \"X-Joomla-Token: $API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"notes\":\"Call before noon\",\"starred\":1}'" } ], "sections": [], "seoTitle": "Change a task", "seoDescription": "PATCH /v1/nexttask/tasks/{id} changes only the fields sent, such as notes, the star or the assignee.", "seoKeywords": null }, { "id": "deleteTask", "slug": "delete-tasks", "pagePath": "api/delete-tasks", "group": "Tasks", "method": "DELETE", "operation": "/v1/nexttask/tasks/{id}", "summary": "Delete a task", "title": "Delete Task", "description": "Deletes a task and its subtasks. It can be restored for 7 days. Needs **Tasks > Delete**.", "stability": "stable", "deprecated": null, "auth": true, "params": [ { "name": "id", "in": "path", "type": "integer", "required": true, "default": null, "enum": null, "example": null, "description": "The record the call is about. An `id` or `ids` in the body is ignored." } ], "requestBody": null, "responses": [ { "status": 200, "description": "The ids deleted.", "example": { "success": true, "message": "string", "messages": "string", "data": { "deleted": [ 1 ] } }, "fields": [], "notes": "" } ], "errors": [ "http_401", "http_403", "http_404" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s -X DELETE \"https://your-site.example/api/index.php/v1/nexttask/tasks/1\" \\\n -H \"X-Joomla-Token: $API_TOKEN\"" } ], "sections": [], "seoTitle": "Delete a task", "seoDescription": "DELETE /v1/nexttask/tasks/{id} deletes a task and its subtasks, restorable for 7 days.", "seoKeywords": null }, { "id": "completeTask", "slug": "tasks-complete", "pagePath": "api/tasks-complete", "group": "Tasks", "method": "POST", "operation": "/v1/nexttask/tasks/{id}/complete", "summary": "Complete or reopen a task", "title": "Complete Task", "description": "`completed` true completes the task, and a repeating task gets its next occurrence.\nFalse reopens it. Needs **Tasks > Complete**.\n", "stability": "stable", "deprecated": null, "auth": true, "params": [ { "name": "id", "in": "path", "type": "integer", "required": true, "default": null, "enum": null, "example": null, "description": "The record the call is about. An `id` or `ids` in the body is ignored." } ], "requestBody": { "contentType": "application/json", "required": true, "description": "", "fields": [ { "name": "completed", "type": "boolean", "required": true, "description": "", "enum": null, "default": null, "children": [] } ], "example": { "completed": true } }, "responses": [ { "status": 200, "description": "The task, and the next occurrence if one was created.", "example": { "success": true, "message": "string", "messages": "string", "data": { "task": { "id": 12, "list_id": 5, "parent_id": 0, "title": "Ship it", "notes": "string", "status": "needsAction", "starred": 1, "due": "2026-10-02 09:00:00", "has_time": 1, "recurrence": "string", "recurrence_next_id": 1, "completed_time": "string", "position": "string", "links": [ {} ], "assigned_to": 1, "assignee_name": "string", "subtask_count": 1, "completed_subtask_count": 1, "access": "owner", "can_complete": true, "deleted_time": "string", "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 }, "item": { "id": 12, "list_id": 5, "parent_id": 0, "title": "Ship it", "notes": "string", "status": "needsAction", "starred": 1, "due": "2026-10-02 09:00:00", "has_time": 1, "recurrence": "string", "recurrence_next_id": 1, "completed_time": "string", "position": "string", "links": [ {} ], "assigned_to": 1, "assignee_name": "string", "subtask_count": 1, "completed_subtask_count": 1, "access": "owner", "can_complete": true, "deleted_time": "string", "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 }, "clone": { "id": 12, "list_id": 5, "parent_id": 0, "title": "Ship it", "notes": "string", "status": "needsAction", "starred": 1, "due": "2026-10-02 09:00:00", "has_time": 1, "recurrence": "string", "recurrence_next_id": 1, "completed_time": "string", "position": "string", "links": [ {} ], "assigned_to": 1, "assignee_name": "string", "subtask_count": 1, "completed_subtask_count": 1, "access": "owner", "can_complete": true, "deleted_time": "string", "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 }, "removed_clone_id": 1 } }, "fields": [], "notes": "" } ], "errors": [ "http_401", "http_403", "http_404" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s -X POST \"https://your-site.example/api/index.php/v1/nexttask/tasks/1/complete\" \\\n -H \"X-Joomla-Token: $API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"completed\":true}'" } ], "sections": [], "seoTitle": "Complete a task", "seoDescription": "POST /v1/nexttask/tasks/{id}/complete completes or reopens a task; a repeating task gets its next occurrence.", "seoKeywords": null }, { "id": "moveTask", "slug": "tasks-move", "pagePath": "api/tasks-move", "group": "Tasks", "method": "POST", "operation": "/v1/nexttask/tasks/{id}/move", "summary": "Move a task", "title": "Move Task", "description": "To another list, next to another task, or under or out of a parent. Needs **Tasks > Edit**.", "stability": "stable", "deprecated": null, "auth": true, "params": [ { "name": "id", "in": "path", "type": "integer", "required": true, "default": null, "enum": null, "example": null, "description": "The record the call is about. An `id` or `ids` in the body is ignored." } ], "requestBody": { "contentType": "application/json", "required": true, "description": "", "fields": [ { "name": "list_id", "type": "integer", "required": false, "description": "", "enum": null, "default": null, "children": [] }, { "name": "after_id", "type": "integer", "required": false, "description": "Place it after this task.", "enum": null, "default": null, "children": [] }, { "name": "before_id", "type": "integer", "required": false, "description": "Place it before this task.", "enum": null, "default": null, "children": [] }, { "name": "parent_id", "type": "integer", "required": false, "description": "Make it a subtask of this task; 0 makes it a top-level task.", "enum": null, "default": null, "children": [] } ], "example": { "list_id": 6 } }, "responses": [ { "status": 200, "description": "The task.", "example": { "success": true, "message": "string", "messages": "string", "data": { "item": { "id": 12, "list_id": 5, "parent_id": 0, "title": "Ship it", "notes": "string", "status": "needsAction", "starred": 1, "due": "2026-10-02 09:00:00", "has_time": 1, "recurrence": "string", "recurrence_next_id": 1, "completed_time": "string", "position": "string", "links": [ {} ], "assigned_to": 1, "assignee_name": "string", "subtask_count": 1, "completed_subtask_count": 1, "access": "owner", "can_complete": true, "deleted_time": "string", "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 } } }, "fields": [], "notes": "" } ], "errors": [ "http_401", "http_403", "http_404", "http_422" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s -X POST \"https://your-site.example/api/index.php/v1/nexttask/tasks/1/move\" \\\n -H \"X-Joomla-Token: $API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"list_id\":6}'" } ], "sections": [], "seoTitle": "Move a task", "seoDescription": "POST /v1/nexttask/tasks/{id}/move moves a task to another list, next to another task, or under a parent.", "seoKeywords": null }, { "id": "restoreTask", "slug": "tasks-restore", "pagePath": "api/tasks-restore", "group": "Tasks", "method": "POST", "operation": "/v1/nexttask/tasks/{id}/restore", "summary": "Restore a deleted task", "title": "Restore Task", "description": "Undoes a delete within 7 days. Needs **Tasks > Delete**.", "stability": "stable", "deprecated": null, "auth": true, "params": [ { "name": "id", "in": "path", "type": "integer", "required": true, "default": null, "enum": null, "example": null, "description": "The record the call is about. An `id` or `ids` in the body is ignored." } ], "requestBody": null, "responses": [ { "status": 200, "description": "What came back.", "example": { "success": true, "message": "string", "messages": "string", "data": { "restored": [ 1 ], "items": [ { "id": 12, "list_id": 5, "parent_id": 0, "title": "Ship it", "notes": "string", "status": "needsAction", "starred": 1, "due": "2026-10-02 09:00:00", "has_time": 1, "recurrence": "string", "recurrence_next_id": 1, "completed_time": "string", "position": "string", "links": [ {} ], "assigned_to": 1, "assignee_name": "string", "subtask_count": 1, "completed_subtask_count": 1, "access": "owner", "can_complete": true, "deleted_time": "string", "created": "string", "created_by": 1, "modified": "string", "modified_by": 1 } ] } }, "fields": [], "notes": "" } ], "errors": [ "http_401", "http_403", "http_404" ], "rateLimit": null, "samples": [ { "lang": "bash", "label": "curl", "code": "curl -s -X POST \"https://your-site.example/api/index.php/v1/nexttask/tasks/1/restore\" \\\n -H \"X-Joomla-Token: $API_TOKEN\"" } ], "sections": [], "seoTitle": "Restore a task", "seoDescription": "POST /v1/nexttask/tasks/{id}/restore brings back a task deleted within the last 7 days.", "seoKeywords": null } ], "errors": [ { "id": "http_401", "status": 401, "code": null, "when": "No valid API token.", "body": null, "global": true }, { "id": "http_403", "status": 403, "code": null, "when": "`FORBIDDEN` when the role or the list does not allow it, `APP_DISABLED` when the feature's app is off.", "body": null, "global": true }, { "id": "http_422", "status": 422, "code": null, "when": "`VALIDATION`, `NESTING` or `QUOTA`, with the reason in `message`.", "body": null, "global": true }, { "id": "http_404", "status": 404, "code": null, "when": "`NOT_FOUND`: no such record, or not one you can reach.", "body": { "success": false, "message": "Not found.", "code": "NOT_FOUND" }, "global": false } ], "rateLimits": [], "webhooks": null, "seoOverview": { "title": "REST API Reference", "description": "Next Task REST API reference: Joomla API token auth, list and task endpoints, bulk actions, the response envelope and error codes.", "keywords": "next task api, joomla rest api, openapi, api token, tasks api, lists api" }, "seoEvents": [], "changelog": [], "generatedBy": "NextExtManager", "generated": "2026-10-31T21:21:03+00:00" }