task

Get one task by its per-project index

Changed on

Returns a single task identified by its per-project index. Useful when resolving human-readable references like "PROJ-42" to a canonical task object. The project path parameter accepts either a numeric project id or the project's identifier (e.g. "PROJ"); values consisting solely of digits are always interpreted as ids. Note that task indexes are reassigned when a task is moved between projects, so long-lived references should use the returned task id instead.

get/projects/{project}/tasks/by-index/{index}

Request

  • Base URL
    /api/v1 (relative, and the document was published on a file host, not at the API’s origin)
  • URL
    /api/v1/projects/{project}/tasks/by-index/{index}
  • Auth
    API key in header Authorization

Path parameters

projectstring required

The project id or the project's identifier

indexinteger required

The task's per-project index

Query parameters

expandstring

If set to subtasks, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. You can only set this to subtasks.

Response

The task

bucket_idinteger

The bucket id. Will only be populated when the task is accessed via a view with buckets. Can be used to move a task between buckets. In that case, the new bucket must be in the same view as the old one.

comment_countinteger

Comment count of this task. Only present when fetching tasks with the expand parameter set to comment_count.

cover_image_attachment_idinteger

If this task has a cover image, the field will return the id of the attachment that is the cover image.

createdstring

A timestamp when this task was created. You cannot change this value.

deleted_atstring

A timestamp when this task was deleted. Soft-deleted tasks are kept for 30 days before they are removed permanently. omitzero keeps the field out of the JSON of regular tasks — it only ever appears on soft-deleted ones (the later trash listing).

descriptionstring

The task description.

doneboolean

Whether a task is done or not.

done_atstring

The time when a task was marked as done. This field is system-controlled and cannot be set via API.

due_datestring

The time when the task is due.

end_datestring

When this task ends.

hex_colorstring

The task color in hex

idinteger

The unique, numeric id of this task.

identifierstring

The task identifier, based on the project identifier and the task's index

indexinteger

The task index, calculated per project

is_favoriteboolean

True if a task is a favorite task. Favorite tasks show up in a separate "Important" project. This value depends on the user making the call to the api.

is_unreadboolean
percent_donenumber

Determines how far a task is left from being done

positionnumber

The position of the task - any task project can be sorted as usual by this parameter. When accessing tasks via views with buckets, this is primarily used to sort them based on a range. Positions are always saved per view. They will automatically be set if you request the tasks through a view endpoint, otherwise they will always be 0. To update them, take a look at the Task Position endpoint.

priorityinteger

The task priority. Can be anything you want, it is possible to sort by this later.

project_idinteger

The project this task belongs to. Must precede done/due_date: xorm orders composite index columns by struct field order.

reactionsModelsReactionMap
related_tasksModelsRelatedTaskMap
repeat_afterinteger

An amount in seconds this task repeats itself. If this is set, when marking the task as done, it will mark itself as "undone" and then increase all remindes and the due date by its amount.

repeat_mode0 | 1 | 2
start_datestring

When this task starts.

time_entries_countinteger

Time entry count of this task. Only present when fetching tasks with the expand parameter set to time_entries_count.

titlestring

The task text. This is what you'll see in the project.

updatedstring

A timestamp when this task was last updated. You cannot change this value.

Changes