NAV Navbar
Logo
cURL

Introduction

Welcome to the UpWave API!

This API is in it’s early infant stages but will indeed help you out if you are looking for ways to list cards and boards. It also have some means of updating your data.

As this API is considered extremely early beta, some sections may be tagged with TODO.

If you have any problems or requests please file an issue in our UpWave API GitHub repo.

API Endpoint

Since UpWave confines each team with its own unique subdomain (e.g. mycompany.upwave.io), the API endpoint will reflect this by being directly below your team location. For example if your team domain is myteam the endpoint will be:

API endpoint example: https://myteam.upwave.io/api/

Authentication

# Authenticate to any API ENDPOINT by adding the Authorization header
curl "<API ENDPOINT>"
  -H 'Authorization: Token <API TOKEN>'

Make sure to replace <API TOKEN> with your own.

For clients to authenticate, the token key should be included in the Authorization HTTP header. The key should be prefixed by the string literal “Token”, with whitespace separating the two strings. For example:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

The token can be obtained by visiting your account settings. Click your profile image, select “Settings” and find your API-Key in the “Account” tab.

Pagination

Requests that return multiple items always comes paginated. The default pagination size is set to 50 whereas the max pagination size is 100. Follow the “next” and “previous” urls to turn the pages. The actual list of items are kept within the results block.

For most of the API endpoints, a page_size parameter can be issued to control the size.

Throttling

All api requests are throttled. This means you will receive a status code of 429 “Too Many Requests” if you exceed our limits. We have two quotas to control this; one per hour (for bursts) and one per day.

Members

A Team has Team Members, a Board has Board Members. A Member is a user account tied to an entity such as Team or Board.

List Team Members

GET https://<TEAM DOMAIN>.upwave.io/api/members/

curl "https://<TEAM DOMAIN>.upwave.io/api/members/"
  -H "Authorization: <API TOKEN>"

The above command returns JSON structured like this:

  {
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
      {
        "id": 1,
        "email": "person@example.com",
        "fullname": "John Doe",
        "firstname": "John",
        "avatar": "https://my.profile.image"
      }
    ]
  }

Arguments

Parameter Format Description
board integer Lists only members that have direct access to the given Board
ordering “created”/“seen” Order result list
page_size integer Size of result-set per page

Boards

An UpWave Board is a surface where Cards live. The Board consist of columns, rows and colors which together forms the structure of the Board.

List Boards

GET https://<TEAM DOMAIN>.upwave.io/api/boards/

curl "https://<TEAM DOMAIN>.upwave.io/api/boards/"
  -H "Authorization: <API TOKEN>"

The above command returns JSON structured like this:

  {
    "count": 1, 
    "next": None,
    "previous": None, 
    "results": [
      {
        "id": 1,
        "title": "My Awesome UpWave Board",
        "purpose": "This Board just has explanatory purpose",
        "created_dt": "2016-07-13T10:33:20.581Z",
        "created_by_user": {
          "id": 1,
          "email": "person@example.com",
          "fullname": "John Doe",
          "firstname": "John",
          "avatar": "https://my.profile.image",
        },
      {
        "id": 2,
        ..
      },
    ]
  }

This endpoint retrieves all the Boards you can access in a paginated fashion. They are ordered by creation date (created_dt) with the newest Board listed first.

Filters

Parameter Format Description
q querystring Search for querystring in Board title
ordering field Order result-set by field (default “title”)
page_size integer Size of result-set per page

Get a Specific Board

GET https://<TEAM DOMAIN>.upwave.io/api/boards/<ID>/

curl "https://<TEAM DOMAIN>.upwave.io/api/boards/1/"
  -H "Authorization: <API TOKEN>"

The above command returns JSON structured like this:

  {
    "id": 1,
    "title": "My Awesome UpWave Board",
    "purpose": "This Board just has explanatory purpose",
    "created_dt": "2016-07-13T10:33:20.581Z",
    "created_by_user": {
      "id": 1,
      "email": "person@example.com",
      "fullname": "John Doe",
      "firstname": "John",
      "avatar": "https://my.profile.image"
    },
    "columns": [
      {
        "state": 1,
        "id": 1,
        "name": "To do"
      },
      {
        "state": 2,
        "id": 2,
        "name": "In progress"
      },
      {
        "state": 3,
        "id": 3,
        "name": "Completed"
      }
    ],
    "rows": [
      {
        "id": 1,
        "name": "Row-1"
      }
    ],
    "colors": [
      {
        "name": "Red",
        "id": 1,
        "hex_color": "#f37477"
      },
      {
        "name": "Yellow",
        "id": 2,
        "hex_color": "#fed562"
      },
      {
        "name": "Green",
        "id": 3,
        "hex_color": "#aed581"
      }
    ]
  }

This endpoint retrieves a specific Board.

Query Parameters

Parameter Default Description
include_members false If set to true, the result will also include members on the board.

Note on Board structure

The Board has some characteristics worth pointing out. The Board structure consists of Colors, Columns and Rows. These 3 dimensions have very different behaviours.

Columns are used for keeping track of Card statuses. The property state on a Column is used as a universal status indicator. When a Card is moved to a Column, the card will inherit the status of that Column.

A Column always has one of these states:

Column state Description
0 Not specified
1 Not started
2 In progress
3 Completed

As a result UpWave can aggregate Card statuses across Boards (more on that in the Cards section. Also, we have built a triggering system on top of this that you may notice.

Currently there are two triggers in effect on all Boards.

Updating a Board

POST https://<TEAM DOMAIN>.upwave.io/api/boards/<ID>/

TODO

Creating a new Board

POST https://<TEAM DOMAIN>.upwave.io/api/boards/

TODO

Deleting a Board

DELETE https://<TEAM DOMAIN>.upwave.io/api/boards/<ID>/

# Deletes Board with id 1
curl "https://<TEAM DOMAIN>.upwave.io/api/boards/1/"
  -X DELETE
  -H "Authorization: <API TOKEN>"

Right? Yes, look right to see how to delete a Board.

Cards

UpWave Cards are information carriers that can hold task-description, comments, files etc.

Watching a Card

A User, when on a watch list to a Card, will be notified on important changes on that Card. The user will automatically be added to the watch list when.. a) the user is assigned a Card, b) the user is mentioned in a Comment on a Card c) the user choose to watch the Card

The only way to unwatch is to update the card with {“watch”: false} This is also the mechanism for how to manually add oneselves to the watch list.

List Cards

GET https://<TEAM DOMAIN>.upwave.io/api/cards/

curl "https://<TEAM DOMAIN>.upwave.io/api/cards/"
  -H "Authorization: <API TOKEN>"

The above command returns JSON structured like this:

  {
    "count": 7, 
    "next": "https://<TEAM DOMAIN>.upwave.io/api/cards/?page=2",
    "previous": None, 
    "results": [
      {
        "id": 4723,
        "title": "A Card",
        "description": "<h1>A Card</h1><p>More text in a paragraph.</p>",
        "color": null,
        "created_dt": "2016-07-13T10:33:26.645Z",
        "created_by_user": {
          "id": 2,
          "email": "person2@example.com",
          "fullname": "Lisa Doe",
          "firstname": "Lisa",
          "avatar": "https://my.profile.image"
        },
        "finished_dt": "2016-08-04T08:53:24.921Z",
        "due_dt": null,
        "assigned": [
          {
            "id": 1,
            "email": "person1@example.com",
            "fullname": "John Doe",
            "firstname": "John",
            "avatar": "https://my.profile.image"
          },
          {
            "id": 2,
            "email": "person2@example.com",
            "fullname": "Lisa Doe",
            "firstname": "Lisa",
            "avatar": "https://my.profile.image"
          },
        ]
      },
      ..
    ]
  }

This endpoint retrieves all the Cards you can access in a paginated fashion. They are ordered by creation date (created_dt) with the newest Card listed first.

Filters

Parameter Format Description
created_by_user integer Filter Cards on what user created them
created_start YYYY-MM-DD Filter Cards that were created on or after this date
created_end YYYY-MM-DD Filter Cards that were created on or before this date
due_start YYYY-MM-DD Filter Cards that have due_dt on or after this date
due_end YYYY-MM-DD Filter Cards that have due_dt on or before this date
finished_start YYYY-MM-DD Filter Cards that were completed on or after this date
finished_end YYYY-MM-DD Filter Cards that were completed on or before this date
finished true/false Filter Cards on whether they are completed or not
state integer Filter Cards based on their column state
board integer Filter Cards based on their parent Board
assigned 1,2,3 Filter Cards based on who are assigned
q querystring Search for querystring in Card title and description
ordering field Order result-set by field (default “-created”)
page_size integer Size of result-set per page

The assigned parameter supports comma separated list which will be OR'ed. For example, to filter Cards that are assigned to either of user-account 1 or 2 you can pass in: ?assigned=1,2

The ordering parameter will order the result-set on the field given. Acceptable fields are: “created”, “finished”, “due”. To specify a descending ordering direction set a minus in front e.g. ?ordering=-created

When filters are combined they will be AND'ed together. For example to list all Cards that were completed in month July 2017, combine filters like so: ?finished_start=2017-07-1&finished_end=2017-07-31

Get a Specific Card

GET https://<TEAM DOMAIN>.upwave.io/api/cards/<ID>/

This endpoint retrieves a specific Card.

curl "https://<TEAM DOMAIN>.upwave.io/api/cards/4723/"
  -H "Authorization: <API TOKEN>"

The above command returns JSON structured like this:

  {
    "id": 4723,
    "title": "A Card",
    "description": "<h1>A Card</h1><p>More text in a paragraph.</p>",
    "color": null,
    "created_dt": "2016-07-13T10:33:26.645Z",
    "created_by_user": {
      "id": 2,
      "email": "person2@example.com",
      "fullname": "Lisa Doe",
      "firstname": "Lisa",
      "avatar": "https://my.profile.image"
    },
    "finished_dt": "2016-08-04T08:53:24.921Z",
    "due_dt": null,
    "assigned": [
      {
        "id": 1,
        "email": "person1@example.com",
        "fullname": "John Doe",
        "firstname": "John",
        "avatar": "https://my.profile.image"
      },
      {
        "id": 2,
        "email": "person2@example.com",
        "fullname": "Lisa Doe",
        "firstname": "Lisa",
        "avatar": "https://my.profile.image"
      },
    ],
    "watched": true
  }

In order to fetch additional data belonging to a Card, such as Comments, Attachments, TaskListItems, use the appropriate API with a card-filter. Example: api/comments/?card=<CARD ID>

Updating a Card

PATCH https://<TEAM DOMAIN>.upwave.io/api/cards/<ID>/

# Updates Card 4723
curl https://<TEAM DOMAIN>.upwave.io/api/cards/4723/
  -H 'Authorization: Token <API_TOKEN>'
  -H "Content-Type: application/json"
  -X POST
  -d '{"description": "My new description", "due_dt": "2017-05-10T09:38:06.459119"}'
Allowed field Type Description
description string plain-text or HTML allowed
due_dt datetime-iso updates the cards due-dt. Pass null to remove due-dt
color color-id updates the color for this Card. Pass null to remove color
archive boolean if true the Card will be moved to the archive
finished boolean toggle the completed state of a Card
assigned id-list will assign this Card to those user accounts
sort_before integer sorts this Card before given Card id (0 will sort last)
watch boolean Watch/Unwatch user for commment notifications on this Card

To update a Card you patch in a JSON object with the fields you’d like to update. For date fields, use UTC.

Creating a new Card

POST https://<TEAM DOMAIN>.upwave.io/api/cards/

# Creates a new Card on Board 311
curl https://<TEAM DOMAIN>.upwave.io/api/cards/
  -H 'Authorization: Token <API_TOKEN>'
  -H "Content-Type: application/json"
  -X POST
  -d '{"description": "A new card", "board": 311}'

The new Card will be sorted last automatically (use update to change it).

Argument Description
description* The content of the Card. May be HTML formatted
board* The parent Board
color Will set the Color of this card
due_dt Will set the due_dt of this card
column Will position the card in this Column (defaults to left-most Column with state 1 if exists else left-most Column)
row Will position the card in this Row (defaults to first Row)

* required field

Deleting a Card

DELETE https://<TEAM DOMAIN>.upwave.io/api/cards/<ID>/

# Deletes Card with id 4723
curl "https://<TEAM DOMAIN>.upwave.io/api/cards/4723/"
  -X DELETE
  -H "Authorization: <API TOKEN>"

Tilt your head right and see how.

TaskListItems

TaskListItems is UpWaves way of handling sub-tasks.

List TaskListItems

GET https://<TEAM DOMAIN>.upwave.io/api/tasklistitems/

curl "https://<TEAM DOMAIN>.upwave.io/api/tasklistitems/"
  -H "Authorization: <API TOKEN>"

The above command returns JSON structured like this:

  {
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
      {
        "id": 11,
        "description": "Write API documentation for TaskListItem",
        "finished_dt": null,
        "sort_index": 0,
        "card": 1
      },
      {
        "id": 12,
        "description": "Write tests for TaskListItem API",
        "finished_dt": "2017-05-18T11:53:41.402858Z",
        "sort_index": 1,
        "card": 2
      }
    ]
  }

This endpoint retrieves all the TaskListItems you can access in a paginated fashion. They are ordered by sort_index which really only makes sense when filtering using the Card parameter.

A TaskListItem is essentially a subtask and consist of a description, a field determining if its finished or not, and a sort index.

Filters

Parameter Format Description
finished true/false Filter TaskListItems on whether they are completed or not
card integer Filter TaskListItems based on their parent Card

Creating a new TaskListItem

POST https://<TEAM DOMAIN>.upwave.io/api/tasklistitems/

# Creates a new TaskListItem on Card 2
curl https://<TEAM DOMAIN>.upwave.io/api/tasklistitems/
  -H 'Authorization: Token <API_TOKEN>'
  -H "Content-Type: application/json"
  -X POST
  -d '{"description": "Write tests for Cmment API", "card": 2}'

The new TaskListItem will be sorted last automatically (use update to change it).

Argument Description
description* The description of the TaskListItem
card* The parent Card

* required field

Updating a TaskListItem

PATCH https://<TEAM DOMAIN>.upwave.io/api/tasklistitems/<ID>/

# Updates TaskListItem 13
curl https://<TEAM DOMAIN>.upwave.io/api/tasklistitems/13/
  -H 'Authorization: Token <API_TOKEN>'
  -H "Content-Type: application/json"
  -X POST
  -d '{"description": "Write tests for Comment API", "finished_dt": "2017-05-10T09:38:06.459119", "sort_before": "12"}'
Allowed field Type Description
description string plain-text
finished boolean toggle the completed state of a TaskListItem
sort_before integer sorts this TaskListItem before given TaskListItem id. (0 will sort last)

Deleting a TaskListItem

DELETE https://<TEAM DOMAIN>.upwave.io/api/tasklistitems/<ID>/

# Deletes TaskListItem with id 12
curl "https://<TEAM DOMAIN>.upwave.io/api/tasklistitems/12/"
  -X DELETE
  -H "Authorization: <API TOKEN>"

Look there ——>

Comments

Comments are posted onto Cards by users. A Comment holds a text message and optionally a list of Attachments.

Mentioning

The content of a Comment may include mentions. If a user is mentioned in a Comment, that user will receive a notification and will also be added to a watch list for the Card.

Mention type Format Description
User @{<USER ID>} Mentions the user with id <USER ID>
Group @{board} Will notify all members on the parent Board

List Comments

GET https://<TEAM DOMAIN>.upwave.io/api/comments/

curl "https://<TEAM DOMAIN>.upwave.io/api/comments/"
  -H "Authorization: <API TOKEN>"

The above command returns JSON structured like this:

  {
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
      {
        "id": 10,
        "card": 6,
        "created_dt": "2017-05-18T11:37:55.938664Z",
        "created_by_user": {
          "id": 1,
          "email": "person@example.com",
          "fullname": "John Doe",
          "firstname": "John",
          "avatar": "https://my.profile.image"
        },
        "last_edited_dt": null,
        "last_edited_by_user": null,
        "text": "Hi @{2}, did you see my previous comment?",
        "attachments": [
          {
            "id": 3,
            "comment": 7,
            "card": 6,
            "name": "My site",
            "source": "link",
            "url": "https://example.com",
            "preview_url": null,
            "cover_url": null,
            "file_size": 0,
          }
        ],
        "mentions": [
          {
          "id": 2,
          "email": "person2@example.com",
          "fullname": "Lisa Doe",
          "firstname": "Lisa",
          "avatar": "https://my.profile.image"
        }
        ]
      }
    ]...
}

Lists Comments you can access in a paginated fashion. They are ordered by creation date (created_dt) with the newest Comment listed first.

Filters

Parameter Format Description
created_by_user integer Filter Comments on what user created them
card integer Filter Comments based on their parent Card
q querystring Search for querystring in Comment text

When filters are combined they will be AND'ed together. For example to list all Comments created by user 74 and which contains the word “Thanks”, simply combine the filters like so: ?created_by_user=74&q=Thanks

Get a specific Comment

GET https://<TEAM DOMAIN>.upwave.io/api/comments/<ID>/

Identical to a Comment in the list-format above.

curl "https://<TEAM DOMAIN>.upwave.io/api/comments/1/"
  -H "Authorization: <API TOKEN>"

The above command returns JSON structured like this:

  {
    "id": 10,
    "card": 6,
    "created_dt": "2017-05-18T11:37:55.938664Z",
    "created_by_user": {
      "id": 1,
      "email": "person@example.com",
      "fullname": "John Doe",
      "firstname": "John",
      "avatar": "https://my.profile.image",
    },
    "last_edited_dt": null,
    "last_edited_by_user": null,
    "text": "The number is 42!",
    "attachments": [
      {
        "id": 3,
        "comment": 7,
        "card": 6,
        "name": "mysite",
        "source": "link",
        "url": "https://mysite.com",
        "preview_url": null,
        "cover_url": null,
        "file_size": 0,
      }
    ]
  }

Updating a Comment

POST https://<TEAM DOMAIN>.upwave.io/api/comments/<ID>/

curl "https://<TEAM DOMAIN>.upwave.io/api/comments/10/"
  -H "Authorization: <API TOKEN>"
  -X POST
  -d '{
        "text": "43!, my mistake"
      }

You are allowed to edit the text in a Comment. Doing so will also update the “last_edited_dt” and “last_edited_by_user”.

Argument Description
text The content of the Comment in plain text format

Creating a new Comment

POST https://<TEAM DOMAIN>.upwave.io/api/comments/

Create new Comments by passing in a text and which Card it should be posted to. A Comment may also carry Attachments.

# Creates a new Comment on Card 2
curl "https://<TEAM DOMAIN>.upwave.io/api/comments/"
  -H "Authorization: <API TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d '{
        "text": "Well done!",
        "card": 2
      }'

# Creates a new Comment with both text and Attachment on Card 2
curl "https://<TEAM DOMAIN>.upwave.io/api/comments/"
  -H "Authorization: <API TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d '{
        "text": "See attached url",
        "attachments": [
          {
            "url": "https://example.com",
            "name": "Example"
          }
        ]
        "card": 2
      }'

Currently the public API only support adding URL-Attachments to a Comment. To make the URL appear as a clickable image, you may set the “preview_url” attribute pointing to an image of your choice. The image URL needs to be behind HTTPS protocol and the image should be 200x200 pixels in size.

Argument Description
card* The parent Card
text The content of the Comment in plain text format
attachments A list of Attachments

* required field

Deleting a Comment

DELETE https://<TEAM DOMAIN>.upwave.io/api/comments/<ID>/

# Deletes Comment with id 10
curl "https://<TEAM DOMAIN>.upwave.io/api/comments/10/"
  -X DELETE
  -H "Authorization: <API TOKEN>"

If you just direct your eyes slightly to the right, you will see how to delete a Comment

Attachments

Attachments may accompany a Comment and holds a resource link to either an uploaded file, a web resource or a Google Drive file.

List Attachments

GET https://<TEAM DOMAIN>.upwave.io/api/attachments/

curl "https://<TEAM DOMAIN>.upwave.io/api/attachments/"
  -H "Authorization: <API TOKEN>"

The above command returns JSON structured like this:

  {
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
      {
        "id": 1,
        "comment": 6,
        "card": 5,
        "name": "sketch.png",
        "source": "uploadedfile",
        "url": "some.image.url,
        "preview_url": "some.image.url",
        "cover_url": "some.image.url",
        "file_size": 5733,
      },
      {
        "id": 2,
        "comment": 6,
        "card": 5,
        "name": "Spreadsheet X",
        "source": "gdrive",
        "url": "https://drive.google.com/.............",
        "preview_url": null,
        "cover_url": null,
        "file_size": 0,
      },
      {
        "id": 3,
        "comment": 7,
        "card": 6,
        "name": "mysite",
        "source": "link",
        "url": "https://mysite.com",
        "preview_url": null,
        "cover_url": null,
        "file_size": 0,
      }
    ]
  }

Filtering options:

Parameter Format Description
comment integer Filter Attachments on their parent Comment
card integer Filter Attachment based on their parent Card
source string Filter Attachments on source (see below)

"source" may be either of "uploadedfile", "link" or "gdrive"

File sizes will only be listed for files that are either uploaded directly (source is “uploadedfile”) or for Google Drive files that has a file size.

Deleting an Attachment

DELETE https://<TEAM DOMAIN>.upwave.io/api/attachments/<ID>/

# Deletes attachment with id 3
curl "https://<TEAM DOMAIN>.upwave.io/api/attachments/3/"
  -X DELETE
  -H "Authorization: <API TOKEN>"

Although you will have to create Attachments using the Comment API, deletion of attachments can be done using the Attachment API. When deleting an Attachment, the comment will be set as edited by you.

Errors

The Upwave API uses the following error codes:

Error Code Meaning
401 Unauthorized – Your API key is wrong
404 Not Found – The specified resource could not be found
429 Too Many Requests – You’re asking for too much, Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.