Worksnaps API reference

New to Corsair? See API access, authentication, and error handling.

Projects

create

projects.create Create a project with a name and description Risk: write

await corsair.worksnaps.api.projects.create({ name: 'Acme storefront', description: 'Front-end work' });

Input

Name	Type	Required	Description
`name`	`string`	Yes	—
`description`	`string`	No	—

Output

Name	Type	Required	Description
`project`	`object`	Yes	—

project full type

{
  id?: number | string | null,
  name?: string | null,
  description?: string | null,
  status?: string | null
}

delete

projects.delete Archive a project; it is not erased and projects.update with status active restores it Risk: write

await corsair.worksnaps.api.projects.delete({ project_id: 3456 });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—

Output

Name	Type	Required	Description
`id`	`number`	Yes	—
`deleted`	`true`	Yes	—

get

projects.get Read one project with its name and description Risk: read

await corsair.worksnaps.api.projects.get({ project_id: 3456 });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—

Output

Name	Type	Required	Description
`project`	`object`	Yes	—

project full type

{
  id?: number | string | null,
  name?: string | null,
  description?: string | null,
  status?: string | null
}

list

projects.list List the projects the token is involved in, optionally with each project members Risk: read

await corsair.worksnaps.api.projects.list({ include_user_assignment: true });

Input

Name	Type	Required	Description
`include_user_assignment`	`boolean`	No	Also return each project user assignments, which are its members.

Output

Name	Type	Required	Description
`projects`	`object[] \| object \| ""`	Yes	—

projects full type

{
  id?: number | string | null,
  name?: string | null,
  description?: string | null,
  status?: string | null
}[] | {
} | ""

update

projects.update Change a project name or description, or restore an archived project Risk: write

await corsair.worksnaps.api.projects.update({ project_id: 3456, name: 'Renamed' });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`name`	`string`	No	—
`description`	`string`	No	—
`status`	`active \| archived`	No	Set active to restore a project that projects.delete archived.

Output

Name	Type	Required	Description
`project`	`object`	Yes	—

project full type

{
  id?: number | string | null,
  name?: string | null,
  description?: string | null,
  status?: string | null
}

Reports

project

reports.project Read time per user and task in one project over at most 30 days Risk: read

await corsair.worksnaps.api.reports.project({ project_id: 3456, user_ids: [12], from_timestamp: 1717232400, to_timestamp: 1717318800 });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`name`	`time_summary \| time_entries`	No	time_summary (the default) totals time per user and task; time_entries lists each entry.
`user_ids`	`number[]`	Yes	The users to report on.
`from_timestamp`	`number`	Yes	Start of the range in Unix seconds, on a 10-minute boundary (a multiple of 600).
`to_timestamp`	`number`	Yes	End of the range in Unix seconds, on a 10-minute boundary.

Output

Name	Type	Required	Description
`time_summary`	`object[] \| object \| ""`	No	—
`time_entries`	`object[] \| object \| ""`	No	—

time_summary full type

{
  project_id?: number | string | null,
  user_id?: number | string | null,
  task_id?: number | string | null,
  task_name?: string | null,
  user_comment?: string | null,
  time_entry_type?: string | null,
  duration_in_minutes?: number | string | null
}[] | {
} | ""

time_entries full type

{
  id?: number | string | null,
  task_id?: number | string | null,
  user_id?: number | string | null,
  project_id?: number | string | null,
  user_comment?: string | null,
  from_timestamp?: string | null,
  logged_timestamp?: string | null,
  duration_in_minutes?: number | string | null,
  type?: string | null,
  task_name?: string | null,
  thumbnail_url?: string | null
}[] | {
} | ""

summary

reports.summary Read time by user, project, task and day across the projects you manage, over at most 30 days Risk: read

await corsair.worksnaps.api.reports.summary({ from_date: '2024-06-01', to_date: '2024-06-07' });

Input

Name	Type	Required	Description
`from_date`	`string`	Yes	First day, YYYY-MM-DD.
`to_date`	`string`	Yes	Last day, YYYY-MM-DD; at most 30 days after from_date.
`timezone_offset`	`number`	No	Hours from UTC for the day boundaries, e.g. -8 or 5.5; defaults to the user timezone.
`project_ids`	`number[]`	No	Defaults to every project you manage.
`user_ids`	`number[]`	No	Defaults to every user in those projects.

Output

Name	Type	Required	Description
`manager_report`	`object[] \| object \| ""`	Yes	—

manager_report full type

{
  user_id?: number | string | null,
  user_name?: string | null,
  project_id?: number | string | null,
  project_name?: string | null,
  date?: string | null,
  task_id?: number | string | null,
  task_name?: string | null,
  type?: string | null,
  duration_in_minutes?: number | string | null
}[] | {
} | ""

Task Assignments

create

taskAssignments.create Assign a user to a task Risk: write

await corsair.worksnaps.api.taskAssignments.create({ project_id: 3456, task_id: 78, user_id: 12 });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`task_id`	`number`	Yes	—
`user_id`	`number`	Yes	—

Output

Name	Type	Required	Description
`task_assignment`	`object`	Yes	—

task_assignment full type

{
  id?: number | string | null,
  user_id?: number | string | null,
  task_id?: number | string | null
}

delete

taskAssignments.delete Remove a user from a task Risk: destructive

await corsair.worksnaps.api.taskAssignments.delete({ project_id: 3456, task_assignment_id: 55 });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`task_assignment_id`	`number`	Yes	—

Output

Name	Type	Required	Description
`id`	`number`	Yes	—
`deleted`	`true`	Yes	—

list

taskAssignments.list List which users are assigned to which tasks in a project Risk: read

await corsair.worksnaps.api.taskAssignments.list({ project_id: 3456 });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—

Output

Name	Type	Required	Description
`task_assignments`	`object[] \| object \| ""`	Yes	—

task_assignments full type

{
  id?: number | string | null,
  user_id?: number | string | null,
  task_id?: number | string | null
}[] | {
} | ""

Tasks

create

tasks.create Create a task in a project Risk: write

await corsair.worksnaps.api.tasks.create({ project_id: 3456, name: 'Build the cart' });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`name`	`string`	Yes	—
`description`	`string`	No	—

Output

Name	Type	Required	Description
`task`	`object`	Yes	—

task full type

{
  id?: number | string | null,
  name?: string | null,
  description?: string | null,
  project_id?: number | string | null
}

delete

tasks.delete Delete a task with the time logged against it; this cannot be undone Risk: destructive

await corsair.worksnaps.api.tasks.delete({ project_id: 3456, task_id: 78 });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`task_id`	`number`	Yes	—

Output

Name	Type	Required	Description
`id`	`number`	Yes	—
`deleted`	`true`	Yes	—

get

tasks.get Read one task Risk: read

await corsair.worksnaps.api.tasks.get({ project_id: 3456, task_id: 78 });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`task_id`	`number`	Yes	—

Output

Name	Type	Required	Description
`task`	`object`	Yes	—

task full type

{
  id?: number | string | null,
  name?: string | null,
  description?: string | null,
  project_id?: number | string | null
}

list

tasks.list List the tasks in a project Risk: read

await corsair.worksnaps.api.tasks.list({ project_id: 3456 });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—

Output

Name	Type	Required	Description
`tasks`	`object[] \| object \| ""`	Yes	—

tasks full type

{
  id?: number | string | null,
  name?: string | null,
  description?: string | null,
  project_id?: number | string | null
}[] | {
} | ""

update

tasks.update Change a task name or description Risk: write

await corsair.worksnaps.api.tasks.update({ project_id: 3456, task_id: 78, name: 'Renamed' });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`task_id`	`number`	Yes	—
`name`	`string`	No	—
`description`	`string`	No	—

Output

Name	Type	Required	Description
`task`	`object`	Yes	—

task full type

{
  id?: number | string | null,
  name?: string | null,
  description?: string | null,
  project_id?: number | string | null
}

Time Entries

byUser

timeEntries.byUser List the time one user logged on a project between two Unix timestamps Risk: read

await corsair.worksnaps.api.timeEntries.byUser({ project_id: 3456, user_id: 12, from_timestamp: 1717232400, to_timestamp: 1717318800 });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`user_id`	`number`	Yes	—
`from_timestamp`	`number`	Yes	Start of the range in Unix seconds, on a 10-minute boundary (a multiple of 600).
`to_timestamp`	`number`	Yes	End of the range in Unix seconds, on a 10-minute boundary.

Output

Name	Type	Required	Description
`time_entries`	`object[] \| object \| ""`	Yes	—

time_entries full type

{
  id?: number | string | null,
  task_id?: number | string | null,
  user_id?: number | string | null,
  project_id?: number | string | null,
  user_comment?: string | null,
  from_timestamp?: string | null,
  logged_timestamp?: string | null,
  duration_in_minutes?: number | string | null,
  type?: string | null,
  task_name?: string | null,
  thumbnail_url?: string | null
}[] | {
} | ""

create

timeEntries.create Log offline time for yourself on an assigned task, from a Unix start time and a duration in minutes Risk: write

await corsair.worksnaps.api.timeEntries.create({ project_id: 3456, task_id: 78, from_timestamp: 1717232400, duration_in_minutes: 90, user_comment: 'Worked on the cart' });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`task_id`	`number`	Yes	—
`from_timestamp`	`number`	Yes	When the work started, in Unix seconds on a 10-minute boundary.
`duration_in_minutes`	`number`	Yes	Worksnaps splits the time into 10-minute entries.
`user_comment`	`string`	No	—

Output

Name	Type	Required	Description
`time_entries`	`object[] \| object \| ""`	Yes	—

time_entries full type

{
  id?: number | string | null,
  task_id?: number | string | null,
  user_id?: number | string | null,
  project_id?: number | string | null,
  user_comment?: string | null,
  from_timestamp?: string | null,
  logged_timestamp?: string | null,
  duration_in_minutes?: number | string | null,
  type?: string | null,
  task_name?: string | null,
  thumbnail_url?: string | null
}[] | {
} | ""

delete

timeEntries.delete Delete a logged time entry; this cannot be undone Risk: destructive

await corsair.worksnaps.api.timeEntries.delete({ project_id: 3456, time_entry_id: 901 });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`time_entry_id`	`number`	Yes	—

Output

Name	Type	Required	Description
`id`	`number`	Yes	—
`deleted`	`true`	Yes	—

get

timeEntries.get Read one time entry, optionally with full-resolution screenshot URLs Risk: read

await corsair.worksnaps.api.timeEntries.get({ project_id: 3456, time_entry_id: 901, full_resolution_url: true });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`time_entry_id`	`number`	Yes	—
`full_resolution_url`	`boolean`	No	Return the full-resolution screenshot URLs rather than the thumbnails.

Output

Name	Type	Required	Description
`time_entry`	`object`	Yes	—

time_entry full type

{
  id?: number | string | null,
  task_id?: number | string | null,
  user_id?: number | string | null,
  project_id?: number | string | null,
  user_comment?: string | null,
  from_timestamp?: string | null,
  logged_timestamp?: string | null,
  duration_in_minutes?: number | string | null,
  type?: string | null,
  task_name?: string | null,
  thumbnail_url?: string | null
}

list

timeEntries.list List the time some users logged on a project between two Unix timestamps Risk: read

await corsair.worksnaps.api.timeEntries.list({ project_id: 3456, user_ids: [12], from_timestamp: 1717232400, to_timestamp: 1717318800 });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`user_ids`	`number[]`	Yes	The users whose time to list; the API requires at least one.
`from_timestamp`	`number`	Yes	Start of the range in Unix seconds, on a 10-minute boundary (a multiple of 600).
`to_timestamp`	`number`	Yes	End of the range in Unix seconds, on a 10-minute boundary.

Output

Name	Type	Required	Description
`time_entries`	`object[] \| object \| ""`	Yes	—

time_entries full type

{
  id?: number | string | null,
  task_id?: number | string | null,
  user_id?: number | string | null,
  project_id?: number | string | null,
  user_comment?: string | null,
  from_timestamp?: string | null,
  logged_timestamp?: string | null,
  duration_in_minutes?: number | string | null,
  type?: string | null,
  task_name?: string | null,
  thumbnail_url?: string | null
}[] | {
} | ""

update

timeEntries.update Move a time entry to another task or change its comment Risk: write

await corsair.worksnaps.api.timeEntries.update({ project_id: 3456, time_entry_id: 901, user_comment: 'Cart checkout' });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`time_entry_id`	`number`	Yes	—
`task_id`	`number`	No	—
`user_comment`	`string`	No	—

Output

Name	Type	Required	Description
`time_entries`	`object[] \| object \| ""`	Yes	—

time_entries full type

{
  id?: number | string | null,
  task_id?: number | string | null,
  user_id?: number | string | null,
  project_id?: number | string | null,
  user_comment?: string | null,
  from_timestamp?: string | null,
  logged_timestamp?: string | null,
  duration_in_minutes?: number | string | null,
  type?: string | null,
  task_name?: string | null,
  thumbnail_url?: string | null
}[] | {
} | ""

User Assignments

create

userAssignments.create Add a member to a project with a role, rate and time-logging windows Risk: write

await corsair.worksnaps.api.userAssignments.create({ project_id: 3456, user_id: 12, role: 'member', hourly_rate: 45.5, flag_allow_logging_time: true });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`user_id`	`number`	Yes	—
`role`	`string`	No	The member role in this project, such as member or manager.
`hourly_rate`	`number`	No	—
`flag_allow_logging_time`	`boolean`	No	—
`window_for_deleting_time`	`number`	No	—
`window_for_adding_offline_time`	`number`	No	—

Output

Name	Type	Required	Description
`user_assignment`	`object`	Yes	—

user_assignment full type

{
  id?: number | string | null,
  user_id?: number | string | null,
  project_id?: number | string | null,
  role?: string | null,
  hourly_rate?: number | string | null,
  flag_allow_logging_time?: boolean | string | number | null,
  window_for_deleting_time?: number | string | null,
  window_for_adding_offline_time?: number | string | null
}

get

userAssignments.get Read one project membership Risk: read

await corsair.worksnaps.api.userAssignments.get({ project_id: 3456, user_assignment_id: 21 });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—
`user_assignment_id`	`number`	Yes	—

Output

Name	Type	Required	Description
`user_assignment`	`object`	Yes	—

user_assignment full type

{
  id?: number | string | null,
  user_id?: number | string | null,
  project_id?: number | string | null,
  role?: string | null,
  hourly_rate?: number | string | null,
  flag_allow_logging_time?: boolean | string | number | null,
  window_for_deleting_time?: number | string | null,
  window_for_adding_offline_time?: number | string | null
}

list

userAssignments.list List the members of a project with their roles and rates Risk: read

await corsair.worksnaps.api.userAssignments.list({ project_id: 3456 });

Input

Name	Type	Required	Description
`project_id`	`number`	Yes	—

Output

Name	Type	Required	Description
`user_assignments`	`object[] \| object \| ""`	Yes	—

user_assignments full type

{
  id?: number | string | null,
  user_id?: number | string | null,
  project_id?: number | string | null,
  role?: string | null,
  hourly_rate?: number | string | null,
  flag_allow_logging_time?: boolean | string | number | null,
  window_for_deleting_time?: number | string | null,
  window_for_adding_offline_time?: number | string | null
}[] | {
} | ""

update

userAssignments.update Change a member hourly rate, time logging or time-logging windows in a project Risk: write

await corsair.worksnaps.api.userAssignments.update({ project_id: 3456, user_assignment_id: 21, hourly_rate: 50 });

Input

Name	Type	Required	Description
`hourly_rate`	`number`	No	—
`flag_allow_logging_time`	`boolean`	No	—
`window_for_deleting_time`	`number`	No	—
`window_for_adding_offline_time`	`number`	No	—
`project_id`	`number`	Yes	—
`user_assignment_id`	`number`	Yes	—

Output

Name	Type	Required	Description
`user_assignment`	`object`	Yes	—

user_assignment full type

{
  id?: number | string | null,
  user_id?: number | string | null,
  project_id?: number | string | null,
  role?: string | null,
  hourly_rate?: number | string | null,
  flag_allow_logging_time?: boolean | string | number | null,
  window_for_deleting_time?: number | string | null,
  window_for_adding_offline_time?: number | string | null
}

Users

create

users.create Create a user; a privileged call that needs the partner API token rather than a normal one Risk: write

await corsair.worksnaps.api.users.create({ login: 'jordan', email: 'jordan@acme.example', first_name: 'Jordan', last_name: 'Ruiz', password: 'a-strong-password' });

Input

Name	Type	Required	Description
`login`	`string`	Yes	—
`email`	`string`	Yes	—
`first_name`	`string`	Yes	—
`last_name`	`string`	Yes	—
`password`	`string`	Yes	—
`timezone_id`	`number`	No	—

Output

Name	Type	Required	Description
`user`	`object`	Yes	—

user full type

{
  id?: number | string | null,
  login?: string | null,
  first_name?: string | null,
  last_name?: string | null,
  email?: string | null,
  timezone_id?: number | string | null
}

get

users.get Read one user Risk: read

await corsair.worksnaps.api.users.get({ user_id: 12 });

Input

Name	Type	Required	Description
`user_id`	`number`	Yes	—

Output

Name	Type	Required	Description
`user`	`object`	Yes	—

user full type

{
  id?: number | string | null,
  login?: string | null,
  first_name?: string | null,
  last_name?: string | null,
  email?: string | null,
  timezone_id?: number | string | null
}

list

users.list List the users on the account Risk: read

await corsair.worksnaps.api.users.list({});

Input: empty object Output

Name	Type	Required	Description
`users`	`object[] \| object \| ""`	Yes	—

users full type

{
  id?: number | string | null,
  login?: string | null,
  first_name?: string | null,
  last_name?: string | null,
  email?: string | null,
  timezone_id?: number | string | null
}[] | {
} | ""

me

users.me Read the account behind the token (without the token itself), which is the cheapest way to check it Risk: read

await corsair.worksnaps.api.users.me({});

Input: empty object Output

Name	Type	Required	Description
`user`	`object`	Yes	—

user full type

{
  id?: number | string | null,
  login?: string | null,
  first_name?: string | null,
  last_name?: string | null,
  email?: string | null,
  timezone_id?: number | string | null
}

update

users.update Change a user email, name or timezone Risk: write

await corsair.worksnaps.api.users.update({ user_id: 12, first_name: 'Jordan' });

Input

Name	Type	Required	Description
`user_id`	`number`	Yes	—
`email`	`string`	No	—
`first_name`	`string`	No	—
`last_name`	`string`	No	—
`timezone_id`	`number`	No	—

Output

Name	Type	Required	Description
`user`	`object`	Yes	—

user full type

{
  id?: number | string | null,
  login?: string | null,
  first_name?: string | null,
  last_name?: string | null,
  email?: string | null,
  timezone_id?: number | string | null
}

Overview

Plugins

Worksnaps API reference

Projects

create

delete

get

list

update

Reports

project

summary

Task Assignments

create

delete

list

Tasks

create

delete

get

list

update

Time Entries

byUser

create

delete

get

list

update

User Assignments

create

get

list

update

Users

create

get

list

me

update

​Projects

​create

​delete

​get

​list

​update

​Reports

​project

​summary

​Task Assignments

​create

​delete

​list

​Tasks

​create

​delete

​get

​list

​update

​Time Entries

​byUser

​create

​delete

​get

​list

​update

​User Assignments

​create

​get

​list

​update

​Users

​create

​get

​list

​me

​update

Projects

create

delete

get

list

update

Reports

project

summary

Task Assignments

create

delete

list

Tasks

create

delete

get

list

update

Time Entries

byUser

create

delete

get

list

update

User Assignments

create

get

list

update

Users

create

get

list

me

update