NAV Navbar

Introduction

Welcome to the Workpath API documentation. This API can be used to build custom clients that integrate with the Workpath platform.

Current Version

The current API version is v1. It is available at https://<your-company>.workpath.com/api/v1.

If you don't know <your-company> subdomain, you can retrieve it with your Workpath user email address.

Authentication

Authentication example:

curl https://<your-company>.workpath.com/api/v1/<endpoint>
  -H "Authorization: Token <your-api-token>"

Make sure to replace <your-api-token> with your API token.

The Workpath API uses tokens to grant access. A guide how to create an API Client and API Token can be found in the Workpath Help Center.

When creating an API Client you have to specify a Workpath user whos access rights will be used when requesting the API. Attributes that are not accessible for this user will be returned as null.

Once you have obtained the API Token, include it in the Authorization header.

Header Value
Authorization Token <your-api-token>

Schema

The API enforces JSON format. Make sure to set the following headers with every request:

Header Value Comment
Accept application/json
Content-Type application/json for POST or PATCH requests

If not specified the API will respond 406 Not Acceptable.

Blank fields are included as null instead of being omitted.

All dates and timestamps are returned in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

Pagination

{
  "goals": [...],
  "pagination": {
    "current_page": 2,
    "items_per_page": 25,
    "total_pages": 6,
    "total_items": 139
  }
}

All endpoints returning multiple items include a pagination object. Add the parameter ?page=2 to your request to access a specific page.

Errors

Error messages are returned like this:
Status: 422 Unprocessable Entity
Content-Type: application/json

{
  "errors": [
    {
      "attribute": "end_date",
      "code": "blank",
      "message": "End date can't be blank"
    }
  ]
}

The Workpath API uses the following error codes:

Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API token is wrong.
403 Forbidden -- You don't have access to this resource.
404 Not Found -- The specified resource could not be found.
406 Not Acceptable -- You requested a format that isn't JSON.
422 Unprocessable Entity -- See the JSON error response body for details.
500 Internal Server Error -- You found an edge case and we will fix it as soon as possible. Please try again later.
503 Service Unavailable -- We are temporarily offline for maintenance. Please try again later.

Goals

Get Goals

curl https://<your-company>.workpath.com/api/v1/goals?query=become&start_date=2019-04-01&end_date=2019-06-30
  -H "Authorization: Token <your-api-token>"

The above command returns JSON structured like this:
Status: 200 OK
Content-Type: application/json

{
  "goals": [
    {
      "description": null,
      "id": 1,
      "kind": "organization",
      "last_status_update_at": "2019-04-26T17:11:16Z",
      "owner": "Bernd Miksch",
      "progress": 0.83,
      "start_date": "2019-04-01",
      "status": 9,
      "target_date": "2019-06-30",
      "team": null,
      "team_id": null,
      "title": "Become a recognized key player in our industry"
    },
    {
      "description": null,
      "id": 6,
      "kind": "team",
      "last_status_update_at": "2019-04-26T17:11:14Z",
      "owner": "Elena Wischer",
      "progress": 0.19,
      "start_date": "2019-04-01",
      "status": 10,
      "target_date": "2019-06-30",
      "team": "Marketing",
      "team_id": 4,
      "title": "Become a well-known and admired social media brand"
    }
  ],
  "pagination": {
    "current_page": 1,
    "items_per_page": 25,
    "total_pages": 1,
    "total_items": 2
  }
}

This endpoint retrieves all goals filtered by the given parameters.

HTTP Request

GET https://<your-company>.workpath.com/api/v1/goals

Query Parameters

Parameter Type Need Description
start_date string required when end_date given start_date of the date range filter. Format: YYYY-MM-DD. When omitted all goals with target_date in the future are returned
end_date string required when start_date given end_date of the date range filter. Format: YYYY-MM-DD. When omitted all goals with target_date in the future are returned
team_id integer optional id of a Workpath team. When set only goals owned by that team will be returned
query string optional query to search against goal title, goal description, all key_result titles and all key_result descriptions
page integer optional number of a specific page. First page will be returned when omitted or out of range

Get Goal Details

curl https://<your-company>.workpath.com/api/v1/goals/1
  -H "Authorization: Token <your-api-token>"

The above command returns JSON structured like this:
Status: 200 OK
Content-Type: application/json

{
  "description": null,
  "draft": false,
  "goal_children_ids": [2, 3],
  "goal_parents_ids": [],
  "id": 1,
  "initiatives": [
    {
      "description": null,
      "id": 1,
      "last_status_update_at": "2019-06-28T10:39:29Z",
      "owner": "Bernd Miksch",
      "status": "in_progress",
      "title": "Raise brand awareness among target group"
    }
  ],
  "key_results": [
    {
      "currency": null,
      "current_value": 10,
      "description": null,
      "id": 1,
      "last_status_update_at": null,
      "milestones": [],
      "owner": null,
      "owner_team": null,
      "progress": 1,
      "start_value": 7,
      "status": 10,
      "target_value": 10,
      "title": "Generate 10% of our revenues through recommendations",
      "type": "percental"
    }
  ],
  "kind": "organization",
  "last_status_update_at": "2019-06-27T12:01:54Z",
  "owner": "Bernd Miksch",
  "progress": 0.83,
  "progress_calculation": "key_results",
  "labels": [
    "Strategic Initiative 1"
  ],
  "start_date": "2019-04-01",
  "status": 9,
  "secret": false,
  "target_date": "2019-06-30",
  "team": null,
  "title": "Become a recognized key player in our industry"
}

HTTP Request

GET https://<your-company>.workpath.com/api/v1/goals/<goal-id>

Query Parameters

Parameter Type Need Description
goal_id integer required in path id of the goal to show details for