skip to Main Content

UpStream has powerful developer features, which can be accessed using the UpStream API module. In this document, we will explain how to use the API.

UpStream expands the standard API functionality built into WordPress. So we recommend that you familiarize yourself with the WordPress API before trying to use the UpStream API functionality.

For more information on the WordPress API, including how to use it, see this.

Getting Started with UpStream API

This section explains how to get up and running with the UpStream API with WordPress. If you’re comfortable with the WordPress API, you can skip this section.

The first thing you need to do in order to use the UpStream API is to install an authentication plugin.

Although you shouldn’t use it for production, for a test installation, the easiest authentication plugin to use is the JSON Basic Authentication plugin. You can download it from Github. Once you have downloaded, installed, and activated it, you can start developing with the API.

For this article, we will be using the Talend API Tester Google Chrome addon, which you can get from the Chrome App Store.

Authentication

Authentication into the UpStream API is purely based on the authenticated WordPress REST API user.

If you have the JSON Basic Authentication plugin enabled, you will need to pass an Authorization header with the username and password of the user you are logging in as.

Note that in order to be able to use the UpStream API, you must be logged into the WordPress REST API as a user with manage_upstream permissions. That means that any user who has access to the UpStream API can manipulate any object, regardless of owner or client.

UpStream Objects

The UpStream API allows access to the following object types:

Object Operations Object URL Component
Project GET, POST, PUT projects
Milestone GET, POST, PUT milestones
Task GET, POST, PUT tasks
Bug GET, POST, PUT bugs
File GET, POST, PUT files
Client GET, POST, PUT clients
A list of the UpStream objects that can be manipulated via the API.

Queries to the API are of the form

https://<yourserver>/wp-json/upstream/v1/<object-url-component>

For example:

https://my-wordpress-server/wp-json/upstream/v1/projects?id=1

UpStream API GET

Now, we will start with the queries. To get any object by ID, you can use an HTTP GET query. The ID is passed as a query parameter. For any GET queries, you must pass the fields you want as an array of field[] parameters.

Here is an example:

https://my-wordpress-server/wp-json/upstream/v1/projects?id=165&fields[]=title&fields[]=description

And here is the query above run:

Performing a project GET query using the UpStream API.

And here is the result:

{"title":"Drawing App","description":""}

When you are querying projects, clients, or milestones, you can use the form above.

When you are querying tasks, files, and bugs, you must pass in the project ID as project_id in the request as well. For example,

https://my-wordpress-server/wp-json/upstream/v1/tasks?id=15ed2d17f52485&fields[]=title&project_id=165

Will return:

{"title":"Design Interface"}

The fields options are below:

Project Fields

Field Description Notes
title The title of the project.
description The description of the project.
status The status of the project. Returns the status text.
categories The categories of this project. Returns a JSON array of WordPress term objects.
assignedTo The WordPress user ID of the owner of the project. Returned as a one element array for compatibility.
startDate The start date of the project. Date formatted as YYYY-MM-DD
endDate The end date of the project. Date formatted as YYYY-MM-DD
clientId The client ID of the client that this project is attached to.
clientUserIds The user IDs of the client users attached to this project.
elapsedTime The total elapsed time in hours for the project. Only available if the Time Tracking module is enabled.

Task Fields

Field Description Notes
title The title of the task.
notes The notes for the task.
status The status of the task. Returns the status text.
assignedTo The WordPress user IDs of the owners.
milestoneId The ID of the milestone this task is attached to.
startDate The start date of the task. Date formatted as YYYY-MM-DD
endDate The end date of the task. Date formatted as YYYY-MM-DD
progress The numerical progress percentage.
elapsedTime The total elapsed time in hours for the project. Only available if the Time Tracking module is enabled.

Milestone Fields

Field Description Notes
title The title of the milestone.
notes The notes for the milestone.
color The color of the milestone.
progress The progress % of the milestone.
categories The categories of this milestone. Returns a JSON array of WordPress term objects.
assignedTo The WordPress user IDs of the owners of the milestone.
startDate The start date of the milestone. Date formatted as m/d/Y
endDate The end date of the milestone. Date formatted as m/d/Y

File Fields

Field Description Notes
title The title of the file.
description The description of the file.
assignedTo The WordPress user IDs of the owners of the file.
fileId The WordPress media ID of the file. Not compatible with private files.

Bug Fields

Field Description Notes
title The title of the bug.
description The description of the bug.
dueDate The due date of the bug. Date formatted as YYYY-MM-DD
severity The severity of the bug.
status The status of the bug.
assignedTo The WordPress user ID of the owner of the bug.
fileId The WordPress media ID of the attached file. Not compatible with private files.

UpStream API POST

You can create an object by doing an HTTP POST to the object URL. When doing this, you must pass the creator user ID in the query string. In addition, in the JSON body of the POST, you must pass the fields that you want to set.

For example, you can create a project by POSTing to the following type of URL:

https://<yourserver>/wp-json/upstream/v1/projects?creator_id=<creator user ID>

You will need to POST a JSON object with the fields that you want to set, but at the minimum, you must pass a title, like this:

{ 
    "title": "my project"
}

For tasks, files, and bugs you must pass in the project ID in the GET URL, like this:

https://<yourserver>/wp-json/upstream/v1/projects?creator_id=<creator user ID>&project_id=<project ID>

You must pass a JSON object in the POST body, with at least the title field filled in. You can pass any other fields as well.

For a full list of fields, with rules and parameters, see the PUT section below.

UpStream API PUT

To modify an object, you can do an HTTP PUT to the object URL. The URL structure is similar to above. For instance, to change a project field, you do a PUT request to:

https://<yourserver>/wp-json/upstream/v1/projects?id=<project ID>

In the PUT body, you pass a JSON object with the field data, in the form above.

For tasks, files, and bugs you must pass in the project ID in the GET URL, like this:

https://<yourserver>/wp-json/upstream/v1/tasks?id=<task ID>&project_id=<project ID>

You can set individual fields, or you can set multiple fields at the same time. Below is a list of all possible fields and their parameters:

Project Fields

Field Description Data Type
title The title of the project. String
description The description of the project. String
status The status of the project. String – must match the name of a status option
categoryIds The IDs of the categories of this project. Array of WordPress taxonomy term IDs. All terms must be from taxonomy ‘project_category’
assignedTo The WordPress user ID of the owner of the project. Single element array
startDate The start date of the project. Date formatted as YYYY-MM-DD
endDate The end date of the project. Date formatted as YYYY-MM-DD
clientId The client ID of the client to attach this project to. Integer — must be a valid client ID.

Task Fields

Field Description Data Type
title The title of the task. String
notes The notes for the task. String
status The status of the task. String – must match the name of a status option
assignedTo The WordPress user IDs of the people assigned to the task. WordPress user ID
milestoneId The ID of the milestone this task is attached to. Integer milestone ID
startDate The start date of the task. Date formatted as YYYY-MM-DD
endDate The end date of the task. Date formatted as YYYY-MM-DD
progress The numerical progress percentage. Integer – UpStream only accepts integer multiples of 5 between 0 and 100. (Example: 0, 5, 10, 15, …)

Milestone Fields

Field Description Data Type
title The title of the milestone. String
notes The notes for the milestone. String
color The color of the milestone. String – HTML color code
categoryIds The category IDs of the milestone. Array of WordPress taxonomy term IDs. All terms must be from taxonomy ‘upst_milestone_category’
assignedTo The WordPress user IDs of the people assigned to the milestone. WordPress user ID
startDate The start date of the milestone. Date formatted as YYYY-MM-DD
endDate The end date of the milestone. Date formatted as YYYY-MM-DD

File Fields

Field Description Data Type
title The title of the file. String
description The description of the file. String
assignedTo The WordPress user IDs of the people assigned to the file. WordPress user ID
fileId The WordPress media ID of the file. You will need to upload the file separately. Private files are not supported by the API

Bug Fields

Field Description Data Type
title The title of the bug. String
description The description of the bug. String
dueDate The due date of the bug. Date formatted as YYYY-MM-DD
severity The severity of the bug. String – must match the name of a severity option
status The status of the bug. String – must match the name of a status option
assignedTo The WordPress user IDs of the people assigned to the bug. WordPress user ID
fileId The WordPress media ID of the attached file. You will need to upload the file separately. Private files are not supported by the API

Examples

Here are some examples of the API.

Get Project Title and Status

Request:

GET https://my-wordpress-server/wp-json/upstream/v1/projects?id=165&fields[]=title&fields[]=status

Response:

{
  "title": "Drawing App",
  "status": "In Progress"
}

Set Project End Date and Status

Request:

PUT https://my-wordpress-server/wp-json/upstream/v1/projects?id=165

Request body:

{"endDate":"2021-01-01","status":"In Progress"}

Result:

Result of performing the above PUT request
Result of performing the above PUT request

Create a Task in a Project

Request:

POST https://my-wordpress-server/wp-json/upstream/v1/tasks?project_id=165&creator_id=1

Request body:

{"title":"My New Task","notes":"This is a new task created by the API."}

Response body:

{
  "id": "15ef602687fe8e"
}

Result:

New task created by the API
New task created by the API

Deleting Objects

Deleting objects is not currently permitted. To avoid issues, you must delete objects from the interface.

Using the API Locally

UpStream has an easy-to-use local API and object model, which allows you to do nearly anything you can do with the interface, such as creating, editing, and updating tasks, projects, clients, bugs, and time records.

The UpStream API module comes with a file under the examples/ folder named local_examples.php. That file contains examples of how to perform most operations using the local UpStream API.

Related Articles