Info

Welcome to the Workstack API documentation.

The Workstack API follows a RESTful architecture. It features easy-to-understand, resource-oriented URLs, and utilizes HTTP response codes to indicate errors. We leverage standard HTTP features, including authentication and HTTP verbs, which are compatible with most HTTP clients. All API responses, including error messages, are returned in JSON format.

API Token

Each API request must include an api_token parameter to authenticate the user. Without it, the server will respond with a 401 Unauthorized error.

You can generate a new API token from the Personal Settings page within the Workstack app.

Data Structure

Users and Teams

Each user is associated with at least one team. To get the currently selected team, use the /api/team endpoint. If you need to switch to a different team, you can call the /api/teams/{id}/switch route. After switching, all future API requests will target the newly selected team.

Projects and Todo Lists

Each team can have multiple projects, which can be assigned to a list of users for write permissions (admin users do not need explicit permissions). Each project can contain multiple todo lists, and within these lists, there can be many individual todos.

Todos and Tasks

A todo represents an abstract task that needs to be completed but is not linked to any user. To assign a todo, you create a task. Multiple tasks can be created for a single todo, with each task potentially assigned to a different user and having a different duration. Tasks can be scheduled with a specific start date and time or left unscheduled, in which case they appear as a sortable stack in the Workstack UI.

Meetings

Meetings can be assigned to multiple users and optionally associated with a specific project.

Holidays

Holidays are divided into two categories: User Holidays and Team Holidays. User Holidays apply to a single user, while Team Holidays apply to all members of the team.

Comments

Comments can be attached to a todo and will always be assigned to the authenticated user making the comment.