Next Task 6.0.0: a task manager for Joomla PHP2Shell: Is Your Joomla Site Safe? What to Do Today Introducing Next Boards: Kanban project and task boards for Joomla Next Exams 6.2.0: Exam Studio, six visual question types, exam embeds and six new languages Building the Future of Joomla Extensions
NextSoftware
Next Task — Documentation

Getting started with the REST API

Next Task answers on Joomla's Web Services application (/api/index.php/v1/nexttask/...). The endpoints run the same code as the app: the same owner / edit / view rules, the same validation and the same response envelope.

Enable It

  1. System > Plugins: enable API Authentication - Joomla Token and Web Services - Next Task.
  2. Users > Manage > (a user) > Joomla API Token: the user copies their token. By default only Super Users may have one; the User - Joomla API Token plugin decides which groups can.
  3. Send the token with every request in the X-Joomla-Token header.
TOKEN="c2hhMjU2OjQyOjk4ZjQ..."
SITE="https://example.com"

curl -H "X-Joomla-Token: $TOKEN" "$SITE/api/index.php/v1/nexttask/lists"

A request without a valid token gets 401. The API acts as that user: they see and change exactly what they can in the app. No role opens another person's list for editing: reading it needs Manage > View all, and the result is read-only. A Super User holds every permission, so they can read other people's lists and change their sharing, but not edit their tasks.

What the user's roles allow applies here too (see Roles), and a write needs both the role and access to the list. The API answers 403 FORBIDDEN when the user lacks:

  • Tasks > View: every endpoint. Without it there is no app, and no API.
  • Tasks > Create: POST tasks.
  • Tasks > Edit: PATCH tasks/{id}, POST tasks/{id}/move, POST tasks/star, and the bulk star, unstar, move and assign.
  • Tasks > Complete: POST tasks/{id}/complete, the bulk complete and reopen, and a POST / PATCH tasks that changes status (or creates a task already completed). A PATCH that changes only status needs Complete alone, not Edit, and runs as POST tasks/{id}/complete does (a repeating task gets its next occurrence; the answer carries task, clone and removed_clone_id besides item). These are also the only writes a task's assignee may make on a list shared with them to view; each task says so in can_complete.
  • Tasks > Delete: DELETE tasks/{id}, POST tasks/{id}/restore and the bulk delete.
  • Tasks > Assign: setting assigned_to to someone other than yourself, in POST tasks, PATCH tasks/{id} or a bulk assign. Assigning to yourself, clearing the assignee and leaving it unchanged need only Edit.
  • Lists > Create, Edit, Delete: POST lists, PATCH lists/{id}, DELETE lists/{id} (on lists you own).
  • Lists > Share: changing the sharing of a list you own. Changing the sharing of a list you do not own needs Manage > Shares.
  • Manage > View all: reading a list or task you cannot reach through ownership or a share, and the oversight filters. What comes back is read-only.

Responses

Every response is JSON in the same envelope:

{ "success": true, "data": { "item": { "id": 12, "title": "Ship it" } }, "message": null }

Failures carry a real HTTP status and a code: 401 AUTH_REQUIRED, 403 FORBIDDEN, 404 NOT_FOUND, 422 VALIDATION (with the reason in message), 403 APP_DISABLED when the app the call belongs to is switched off in the App Manager. assigned_to, list_id, parent_id and id must be whole numbers (an empty value means none): anything else is 422 VALIDATION.

Endpoints

Every endpoint, with its parameters, request bodies, responses and code samples, is under API Reference in the sidebar of this tab.

The {id} in a path decides which record a call is about. An id (or ids) in the body of such a call is ignored.

Due dates are written in the site's timezone (Global Configuration > Server > Website Time Zone), without a zone suffix.

Examples

# Create a task, then complete it
ID=$(curl -s -X POST -H "X-Joomla-Token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"title": "Call the supplier", "list_id": 5}' \
  "$SITE/api/index.php/v1/nexttask/tasks" | jq .data.item.id)

curl -s -X POST -H "X-Joomla-Token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"completed": true}' "$SITE/api/index.php/v1/nexttask/tasks/$ID/complete"

# Everything overdue for me
curl -s -H "X-Joomla-Token: $TOKEN" "$SITE/api/index.php/v1/nexttask/tasks?view=overdue"

# Star three tasks at once
curl -s -X POST -H "X-Joomla-Token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"ids": [11, 12, 13], "starred": true}' "$SITE/api/index.php/v1/nexttask/tasks/star"

Assigning a task (assigned_to) only works for someone who can reach its list. Anyone else is refused with 422 and errors.assigned_to = "not_a_member".

All Extensions