v8 Migration Guide
This guide will help you migrate from API v8 to API v9.
caution
The v9 API added new entities like the organization, hence the interface was extended and these concepts are not migrated from v8. Read through our v9 announcement and Getting Started for more information.
v8 -> v9 mapping
info
All not explicitly listed endpoints can be considered available as 1 to 1 replacement, changing v8 to v9 in the endpoint URL.
When v9 endpoints is marked -, it means the endpoint is no longer available. More details provided in additional notes.
tip
If you are looking for a pattern, most of the domain entities moved their path under workspace, for instance POST /clients will be available under /workspaces/{workspace_id}/clients/{client_id}.
Clients
| Verb | v8 | v9 | Additional Notes |
|---|---|---|---|
| GET | /clients | /me/clients | Retrieves details for all clients that the current API user can access. v9 payload adds archived, creator_id, and permissions properties to each object. |
| POST | /clients | /workspaces/{workspace_id}/clients | Creates clients |
| PUT | /clients/{client_id} | /workspaces/{workspace_id}/clients/{client_id} | Modifies a client |
| GET | /clients/{client_id} | /workspaces/{workspace_id}/clients/{client_id} | Retrieves details for a specific client |
| DELETE | /clients/{client_id} | /workspaces/{workspace_id}/clients/{client_id} | Deletes a client |
NOTE: the new POST /workspaces/{workspace_id}/clients/{client_id}/archive and /workspaces/{workspace_id}/clients/{client_id}/restore endpoints are also available. These allow clients to be archived instead of deleted, for data management purposes.
Invitations
| Verb | v8 | v9 | Additional Notes |
|---|---|---|---|
| POST | /workspaces/{workspace_id}/invite | /organizations/{organization_id}/invitations | Invites a user to an organization |
| PUT | /invitations/{invitation_code}/resend | /organizations/{organization_id}/invitations/{invitation_code}/resend | Resends an existing invitation to the target user |
| POST | /invitations/{invitation_code}/accept | /organizations/invitations/{invitation_code}/accept | Accepts an invitation |
| POST | /invitations/{invitation_code}/reject | /organizations/invitations/{invitation_code}/reject | Rejects an invitation |
Misc
| Verb | v8 | v9 | Additional Notes |
|---|---|---|---|
| POST | /signups | /signup | |
| GET | /timeline_settings | - | Can be retrieved via the /me/preferences endpoint |
| POST | /timeline_settings | - | Can be updated via the /me/preferences endpoint |
| POST | /sessions | /me/sessions | |
| DELETE | /sessions | /me/sessions | |
| POST | /reset_token | /me/reset_token | |
| POST | /alerts | /workspaces/{workspace_id}/alerts | |
| DELETE | /alerts/{alert_id} | /workspaces/{workspace_id}/alerts/{alert_id} | |
| GET | /dashboard/{workspace_id} | /workspaces/{workspace_id}/dashboard/all_activity | Also available more specific /most_active and /top_activity |
| POST | /user_groups | - | No longer available. Use the new user group endpoints. |
| DELETE | /user_groups | - | No longer available. Use the new user group endpoints. |
Projects
| Verb | v8 | v9 | Additional Notes |
|---|---|---|---|
| GET | /projects | /me/projects | Lists projects accessible by API user. /me/projects/paginated also available |
| POST | /projects | /workspaces/{workspace_id}/projects | Creates a project |
| GET | /projects/{project_id} | /workspaces/{workspace_id}/projects/{project_id} | Retrieves the details of a specific project. To retrieve all projects, you can paginate through GET /workspaces/{workspace_id}/projects, or use report utility endpoints to quickly retrieve names for specific ids |
| PUT | /projects/{project_id} | /workspaces/{workspace_id}/projects/{project_id} | Updates a project. A PATCH action is also available for uniform bulk editing. |
| DELETE | /projects/{project_id} | /workspaces/{workspace_id}/projects/{project_id} | Deletes a project. Projects can be archived instead, through the PUT or PATCH actions detailed above with the payload {"active": false}. |
| GET | /projects/{project_id}/project_groups | /workspaces/{workspace_id}/project_groups | Retrieves all project groups for a workspace, which represents the user groups assigned to projects. |
| POST | /project_groups | /workspaces/{workspace_id}/project_groups | Assigns a user group to a project. |
| DELETE | /project_groups/{project_group_id} | /workspaces/{workspace_id}/project_groups/{project_group_id} | Unassigns a user group from a project. |
| GET | /projects/{project_id}/project_users | /workspaces/{workspace_id}/project_users | Retrieves all project users for a workspace, which represents the users assigned to projects. |
| POST | /project_users | /workspaces/{workspace_id}/project_users | Assigns a user to a project. |
| PUT | /project_users/{project_user_id} | /workspaces/{workspace_id}/project_users/{project_user_id} | Updates a project user. |
| DELETE | /project_users/{project_user_id} | /workspaces/{workspace_id}/project_users/{project_user_id} | Unassigns a user from a project. |
Tags
| Verb | v8 | v9 | Additional Notes |
|---|---|---|---|
| POST | /tags | /workspaces/{workspace_id}/tags | |
| PUT | /tags/{tag_id} | /workspaces/{workspace_id}/tags/{tag_id} | |
| DELETE | /tags/{tag_id} | /workspaces/{workspace_id}/tags/{tag_id} |
Tasks
| Verb | v8 | v9 | Additional Notes |
|---|---|---|---|
| GET | /tasks | /me/tasks | |
| POST | /tasks | /workspaces/{workspace_id}/projects/{project_id}/tasks | |
| DELETE | /tasks/{task_id} | /workspaces/{workspace_id}/projects/{project_id}/tasks/{task_id} | |
| GET | /tasks/{task_id} | /workspaces/{workspace_id}/projects/{project_id}/tasks | |
| PUT | /tasks/{task_id} | /workspaces/{workspace_id}/projects/{project_id}/tasks/{task_id} |
Time Entries
| Verb | v8 | v9 | Additional Notes |
|---|---|---|---|
| GET | /time_entries | /me/time_entries | |
| GET | /time_entries/start | - | Creates a new running time entry. No longer available. Use POST /workspaces/{workspace_id}/time_entries instead, with a negative duration. |
| POST | /time_entries/start | /workspaces/{workspace_id}/time_entries | To create a new running time entry, call this endpoint with a negative duration. |
| GET | /time_entries/current | /me/time_entries/current | Retrieves the current running time entry. |
| GET | /time_entries/{time_entry_id}/stop | - | Stops the current running time entry. No longer available. Use PATCH /workspaces/{workspace_id}/time_entries/{time_entry_id}/stop instead. |
| POST | /time_entries/{time_entry_id}/stop | /workspaces/{workspace_id}/time_entries/{time_entry_id}/stop | Stops the current time entry. In v9 the verb is now PATCH. |
| PUT | /time_entries/{time_entry_id} | /workspaces/{workspace_id}/time_entries/{time_entry_id} | Updates a time entry. |
| POST | /time_entries/{time_entry_id} | - | Use PUT /workspaces/{workspace_id}/time_entries/{time_entry_id} instead. |
| DELETE | /time_entries/{time_entry_id} | /workspaces/{workspace_id}/time_entries/{time_entry_id} | |
| GET | /time_entries/{time_entry_id} | /me/time_entries/{time_entry_id} | You can use the detailed report endpoints to retrieve multiple time entries. |
Workspace
| Verb | v8 | v9 | Additional Notes |
|---|---|---|---|
| GET | /workspaces | /workspaces | Also available as /me/workspaces |
| POST | /workspaces/{workspace_id}/reset_token | /me/reset_token | |
| DELETE | /workspaces/{workspace_id}/leave | /organizations/{organization_id}/users/leave | |
| GET | /workspaces/{workspace_id}/workspace_users | /workspaces/{workspace_id}/users | |
| PUT | /workspace_users/{workspace_user_id} | /workspaces/{workspace_id}/workspace_users/{workspace_user_id} | |
| DELETE | /workspace_users/{workspace_user_id} | /workspaces/{workspace_id}/workspace_users/{workspace_user_id} |