Skip to main content

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

Verbv8v9Additional Notes
GET/clients/me/clientsRetrieves 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}/clientsCreates 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

Verbv8v9Additional Notes
POST/workspaces/{workspace_id}/invite/organizations/{organization_id}/invitationsInvites a user to an organization
PUT/invitations/{invitation_code}/resend/organizations/{organization_id}/invitations/{invitation_code}/resendResends an existing invitation to the target user
POST/invitations/{invitation_code}/accept/organizations/invitations/{invitation_code}/acceptAccepts an invitation
POST/invitations/{invitation_code}/reject/organizations/invitations/{invitation_code}/rejectRejects an invitation

Misc

Verbv8v9Additional 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_activityAlso 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

Verbv8v9Additional Notes
GET/projects/me/projectsLists projects accessible by API user. /me/projects/paginated also available
POST/projects/workspaces/{workspace_id}/projectsCreates 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_groupsRetrieves all project groups for a workspace, which represents the user groups assigned to projects.
POST/project_groups/workspaces/{workspace_id}/project_groupsAssigns 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_usersRetrieves all project users for a workspace, which represents the users assigned to projects.
POST/project_users/workspaces/{workspace_id}/project_usersAssigns 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

Verbv8v9Additional 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

Verbv8v9Additional 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

Verbv8v9Additional 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_entriesTo create a new running time entry, call this endpoint with a negative duration.
GET/time_entries/current/me/time_entries/currentRetrieves 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}/stopStops 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

Verbv8v9Additional Notes
GET/workspaces/workspacesAlso 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}
© 2024 Toggl. All rights reserved.