Skip to content

Lists

The list object

{
    "id": 78,
    // canonical url for this list
    "changemap_url": "https://changemap.co/hellocode/changemap/7-suggestions/",
    "name": "Suggestions",
    // a list's role defines how it's displayed and its default permissions
    "role": {
        "name": "Suggestions",
        "slug": "suggestions",
        // hex colour for the list's icon
        "colour": "46d6ff"
    },
    // does the list allow end-user suggestions
    "suggestions": true,
    // does the list allow comments
    "comments": true,
    // does the list allow votes
    "votes": true,
    // how many tasks are shown on the map page
    "display_count": 10
}

The valid roles for a list are:

Name Slug Description
Suggestions suggestions Tasks awaiting action that haven't yet moved to another status
Under consideration under_consideration Tasks that have graduated from suggestions but aren't guaranteed to be undertaken
Rejected rejected Tasks that won't be undertaken ever
On hold on_hold Tasks that won't be undertaken in the short-term
Planned planned Tasks that are planned (I'm starting to think this table is a little redundant)
In progress in_progress Tasks that are underway
Completed completed Tasks whose work is complete

Lists will be ordered in the map based on their role's order in the table above.

Get all lists for a map

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

Request

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

import requests

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

Response

Returns a paged list of lists.

{
    "count": 5,
    "next": null,
    "previous": null,
    "results": [
        { 
            // json list object
        }
    ]
}

Get a specific list

This returns a list object without its tasks. Pass the list's ID in the URL to specify which list.

If you're looking for all tasks in a list, use the get all tasks endpoint combined with the list ID as a filter parameter.

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

Request

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

import requests

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

Response

Returns the list object or a HTTP 404.

{
    "id": 7,
    "name": "Suggestions",
    // snip...
}

Create a list

Info

Only allowed for tokens with read, write, and manage scope

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

Parameters

Send a JSON object with the following fields.

Name Required Value
name Required String name
role Required String slug of the role type. Valid values:
suggestions, under_consideration, rejected, on_hold, planned,in_progress, completed
suggestions Boolean, whether the list allows end-user suggestions
votes Boolean, whether the list's tasks can be voted on
comments Boolean, whether the list's tasks can be commented on
display_count Integer of how many tasks to display on the map home page

Request

curl "https://changemap.co/api/1/map/lists/create/" \
  -X "POST" -d "{name: 'Blocked', role: 'on_hold'}" \
  -H "Authorization: Token [your_token]" \
  -H "Content-type: application/json"

import requests
import json

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

obj = json.dumps({"name": "Blocked",
    "role": "on_hold"})

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 list object as JSON. Errors with your data will return a HTTP 400 including a list of validation errors. 

{
    "id": 79,
    "changemap_url": "https://changemap.co/hellocode/changemap/79-blocked/",
    // snip...
}

Update a list

Info

Only allowed for tokens with read, write, and manage scope

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

POST https://changemap.co/api/1/map/lists/: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 list'.

Request

Here's an example of disallowing comments for a list.

curl "https://changemap.co/api/1/map/lists/1/edit/" \
  -X "POST" -d "comments=false"
  -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/lists/{pk}/edit/"

update = json.dumps({
    "comments": false,
})

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

Response

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

{
    "id": 7,
    "changemap_url": "https://changemap.co/team/map/7-suggestions/",
    // snip...
}

Delete a list

Info

Only allowed for tokens with read, write, and manage scope

Danger

Tasks within this list will also be deleted!

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

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

Request

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

import requests

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

Response

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