Docs

Update a task

Preview· P9
PATCH
/tasks/{task_id}

Changes a task. Name the version you read: a stale one is version_stale (409), and nothing changes. A date given as an empty string clears it.

Scope: tasks:write

Authorization

headerAuthorizationBearer <token>

Send Authorization: Bearer <token> on every request. The token is one of:

PrefixWhat it isWhere it may be used
agoo_sk_live_Secret key, live modeYour servers only
agoo_sk_test_Secret key, test modeYour servers only
agoo_pk_live_Publishable key, live modeBrowsers and apps: create pre-registrations and bookings, read public booking types (with their intake questions) and their free slots, read the visit types open for pre-registration with their public forms. Never lists people.
agoo_pk_test_Publishable key, test modeAs above, in test mode
agoo_rk_live_Agoo Reviews key, live mode: a business on Agoo Reviews on its own, on Reviews BusinessYour servers only: the Reviews operations, for that business and the branches the key names
agoo_rk_test_Agoo Reviews key, test modeAs above, on any level: it reads the business's reviews and checks every write without saving it
agoo_ck_live_Check API key, live mode, for a Check API partnerYour servers only: the Checks operations (checks:read), billed per check
agoo_ck_test_Check API key, test modeAs above, answering only the published test values, never billed

Admins create keys in Console → Developers → API keys and choose each key's scopes; a business on Agoo Reviews on its own creates its keys in its business area on agoo.reviews, under Developers; a Check API partner creates its keys in its partner area on agoo.reviews. A key is shown once. Never put a secret key in a URL, a browser or a mobile app.

Scope: tasks:write

Path Parameters

task_id*string
Match^task_[0-7][0-9a-hjkmnp-tv-z]{25}$

Query Parameters

version*integer

The version you read.

Formatint64
Range1 <= value

Header Parameters

Idempotency-Key*string

A UUID you generate for this operation. If you retry with the same key within 24 hours, Agoo returns the original response instead of acting twice. While the first request is still running, a retry returns conflict. Reusing a key with a different request returns idempotency_key_reused. Responses with rate_limited, internal_error or unavailable aren't stored, so retry those with the same key.

Formatuuid

Request Body

application/json
  1. body

A task's fields. A date given as an empty string clears it. Quantities are decimal strings.

title?string
Lengthlength <= 500
description?string
Lengthlength <= 20000
acceptance?string

What done means.

Lengthlength <= 5000
container_id?string

Which list. A key has to name one.

parent_id?string

A parent task. Subtasks go at most four levels deep.

owner_person_id?string

Whoever is accountable. Empty: nobody yet (triage).

priority?string
Value in"urgent""high""medium""low"
status_category?string

Where a new task starts.

Value in"backlog""ready""in_progress"
start_on?string

A calendar day, never an instant.

start_at?string

An instant, with start_tz.

start_tz?string
Lengthlength <= 64
due_on?string

A calendar day, never an instant.

due_at?string

An instant, with due_tz.

due_tz?string
Lengthlength <= 64
planned_finish_on?string
estimate_value?string

A decimal string.

estimate_unit?string
Value in"minutes""hours""days""points"""
remaining_value?string

A decimal string.

required?boolean

A parent can't finish while this is open.

tags?array<string>
Itemsitems <= 30
why?string

Why it's going to this person.

Lengthlength <= 500
client_id?string

Your id for this capture: sending it again finds the same task.

Formatuuid

Response Body

The task.

application/json
  1. response

A task. A date is a day or an instant, never one pretending to be the other, and its state is a category with no ambiguous done flag.

id*TaskId
Match^task_[0-7][0-9a-hjkmnp-tv-z]{25}$
ref_no?integer
Formatint64
title*string
description?string
acceptance?string
kind?string
Value in"task""approval""acknowledgement""checklist_item"
parent_id?string
container?

The list it lives in: id, name, kind, visibility and workflow_id.

owner?

Whoever is accountable: id and name. Absent in triage.

priority?string
Value in"urgent""high""medium""low"
status?

id, name (the organisation's own) and category (backlog, ready, in_progress, blocked, in_review, completed, cancelled).

start_on?string
Formatdate
due_on?string
Formatdate
due_at?string
Formatdate-time
due_tz?string
tags?array<string>
source?

Where it came from, if anywhere.

completion_outcome?string
Value in"done""skipped""blocked""override""source_confirmed""cancelled"
series_id?string

The repeating task it's one occurrence of.

occurrence_key?string

Its identity in that series: the date in the series' time zone, or the task before it for one that repeats on completion.

version*integer

Name this when you change it.

Formatint64
created_at?string
Formatdate-time
updated_at?string
Formatdate-time
curl -X PATCH 'https://api.agoohq.com/v1/tasks/string?version=1' \  -H 'Idempotency-Key: 3f6b2a1e-8c4d-4f7a-9b2e-5d1c0a7e9f64' \  -H 'Content-Type: application/json' \  -d '{}'
{  "id": "string",  "ref_no": 0,  "title": "string",  "description": "string",  "acceptance": "string",  "kind": "task",  "parent_id": "string",  "container": {},  "owner": {},  "priority": "urgent",  "status": {},  "start_on": "2019-08-24",  "due_on": "2019-08-24",  "due_at": "2019-08-24T14:15:22Z",  "due_tz": "string",  "tags": [    "string"  ],  "source": {},  "completion_outcome": "done",  "series_id": "string",  "occurrence_key": "string",  "version": 0,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}