Skip to content

Tasks

The task object

{
    "id": 1,
    // canonical url for the task on the site
    "changemap_url": "https://changemap.co/team/map/task/1-jira-integration/",
    // the list this task currently belongs to
    "parent": {
        "id": 1,
        "name": "Suggestions",
        "role": {
            "name": "Suggestions",
            "colour": "46d6ff"
        }
    },
    // the user who created the task
    "author": {
        "id": 2090,
        "first_name": "Test",
        "last_name": "User",
        // email is visible for team members
        "email": null,
        // denotes if the author is a team member
        "staff": false
    },
    "title": "Jira integration",
    "category": {
        "name": "Operations",
        "emoji_shortname": ":factory:"
    },
    // raw markdown
    "description": "Please integrate with Jira",
    // markdown parsed into html
    "parsed_description": "<p>Please integrate with Jira</p>",
    "created": "2022-12-05T14:39:01.193631+11:00",
    "modified": "2022-12-05T14:39:01.194032+11:00",
    "list_arrival": "2022-12-05T14:39:01.193648+11:00",
    // tasks can contain a related URL
    "url": "https://jira.atlassian.com",
    // pending tasks are hidden end-user suggestions that are not yet approved
    "pending": true,
    // comments can be locked
    "lock_comments": false,
    "votes_count": 0,
    "subscribers_count": 0,
    "comments_count": 2
}

Get all tasks

GET https://changemap.co/api/1/map/tasks/

Tasks can be filtered by various criteria.

Parameters

All parameters are optional, and combinations of any of these are allowed.

Name Value
title String used for a case-insensitive LIKE match
pending Boolean
list_id Integer ID of the task's parent list
list_name String name of the task's parent list
category_name String name of the task's category
category_emoji String of the category's emoji shortname
author_id Integer ID of the user who created the task
created_min String date or datetime in ISO 8601 format, oldest created datetime allowed
created_max Same as created_min but for the most recent datetime allowed
modified_min Same as created_min but for last modified datetime
modified_max Same as created_max but for last modified datetime
list_arrival_min Same as created_min but for the time the task arrived in current list
list_arrival_max Same as created_max but for the time the task arrived in current list

Request

curl "https://changemap.co/api/1/map/tasks/" \
  -H "Authorization: Token [your_token]" \
  -d "created_min=2022-12-01"

import requests

url = "https://changemap.co/api/1/map/tasks/"
requests.get(url,
    params={'created_min': '2022-12-01'},
    headers={'Authorization':'Token [your_token]'})

Response

Returns a paged list of tasks.

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        { 
            // json task object
        }
    ]
}

Get a specific task

Pass the task ID in the URL to specify which task.

GET https://changemap.co/api/1/map/tasks/:id/

Request

curl "https://changemap.co/api/1/map/tasks/1/" \
  -H "Authorization: Token [your_token]"

import requests

pk = 1
url = f"https://changemap.co/api/1/map/tasks/{pk}/"
requests.get(url,
    headers={'Authorization':'Token [your_token]'})

Response

Returns the task object or a HTTP 404.

{
    "id": 1,
    "changemap_url": "https://changemap.co/team/map/task/1-jira-integration/",
    // snip...
}

Create a task

The task's author will be the name you gave this API token.

POST https://changemap.co/api/1/map/tasks/create/

Parameters

Send a JSON object with the following fields.

Name Required Value
parent Required Integer ID of the parent list
title Required String title
description Markdown string, the body of the task
category String name of the category
url String of the task's related URL
pending Boolean, pending status means the task is hidden until approved
lock_comments Boolean, set to true to disallow new comments

Request

curl "https://changemap.co/api/1/map/tasks/create/" \
  -X "POST" -d "{parent:3, title: 'My test task', description: 'This is a test'}" \
  -H "Authorization: Token [your_token]" \
  -H "Content-type: application/json"

import requests
import json

url = "https://changemap.co/api/1/map/tasks/create/"

obj = json.dumps({"parent":3, 
    "title": 'My test task', 
    "description": 'This is a test'})

requests.post(url, data=obj,
    headers={'Authorization':'Token [your_token]',
    'Content-type':'application/json'})

Response

A successful response returns a HTTP 201 Created and the new task object as JSON. Errors with your data will return a HTTP 400 including a list of validation errors. 

{
    "id": 101,
    "changemap_url": "https://changemap.co/team/map/task/101-my-test-task/",
    // snip...
}

Update a task

Pass the task ID in the URL to specify which task.

POST https://changemap.co/api/1/map/tasks/:id/edit/

Parameters

Send a JSON object or form-encoded parameters corresponding to the partial fields you'd like to update. See the list of valid fields under 'create a task'.

Request

Here's an example of moving a task to a new list.

curl "https://changemap.co/api/1/map/tasks/1/edit/" \
  -X "POST" -d "parent=3"
  -H "Authorization: Token [your_token]" \
  -H "Content-type: application/x-www-form-urlencoded"

import requests
import json

pk = 1
url = f"https://changemap.co/api/1/map/tasks/{pk}/edit/"

update = json.dumps({
    "parent": 3,
})

requests.post(url, data=update,
    headers={'Authorization':'Token [your_token]',
    'Content-type':'application/json'})

Response

Returns the updated task object. Error responses include a HTTP 400 if your data was invalid, or a HTTP 404 if the task wasn't found.

{
    "id": 1,
    "changemap_url": "https://changemap.co/team/map/task/1-jira-integration/",
    // snip...
}

Delete a task

Use the DELETE method and pass the task ID to specify which task.

DELETE https://changemap.co/api/1/map/tasks/:id/

Request

curl "https://changemap.co/api/1/map/tasks/1/" \
  -X "DELETE" -H "Authorization: Token [your_token]"

import requests

pk = 1
url = f"https://changemap.co/api/1/map/tasks/{pk}/"
requests.delete(url,
    headers={'Authorization':'Token [your_token]'})

Response

Returns an empty HTTP 204 if successful, or HTTP 404 if not found.