TeamGantt logo
API docs by Redocly

TeamGantt API

Authentication

The TeamGantt API uses a token-based authentication.

In order to use the API, you need to authenticate the requests using an API Token. You can manage your project's API Tokens by visiting https://app.teamgantt.com/admin/developers/tokens.

You need to include this token on every request you make to TeamGantt API. For that, add an Authorization header to the request with the content Bearer API_TOKEN, replacing API_TOKEN with your API Token.

curl -X GET "https://api.teamgantt.com/v1/current_user" -H "Authorization: Bearer API_TOKEN"

boards

Manage boards, columns, and cards

List all boards

Retrieves all kanban boards accessible to the authenticated user.

Boards can be filtered by status (active or closed). The response includes board metadata, associated users, and team information.

Authentication required: Yes (Bearer token)

Permissions: Returns only boards the user has access to

Default behavior: Returns active boards only unless status filter is specified

Use cases:

  • View all available boards for project management
  • Filter archived (closed) boards
  • See team board assignments
Authorizations:
personalAccessToken
query Parameters
status
string
Default: "active"
Enum: "active" "closed"
Example: status=active

Filter boards by status

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a board

Creates a new kanban board within a company.

Boards provide a visual way to organize and track tasks using columns and cards. Each board must belong to a company and can optionally be starred by the creator.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the company

UUID Handling: The id field is optional. If not provided, a UUID will be auto-generated. If provided, it must be a valid UUID and unique.

Starring: Set is_starred: true to automatically star the board for quick access.

Use cases:

  • Create workflow boards for different project phases
  • Set up team-specific boards
  • Organize tasks by department or function
Authorizations:
personalAccessToken
Request Body schema: application/json
required

Board data to create

id
string <uuid>

Optional UUID for the board (auto-generated if not provided)

name
required
string [ 1 .. 255 ] characters

Name of the board

company_id
required
integer

ID of the company that owns this board

is_starred
boolean
Default: false

Whether to star the board for the current user

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Project Board",
  • "company_id": 123456
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create a column on a board

Creates a new column on an existing kanban board.

Columns organize cards into workflow stages (e.g., "To Do", "In Progress", "Done"). Columns can optionally auto-move cards and auto-set task progress based on rules.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the board

UUID Handling: The id field is optional. If not provided, a UUID will be auto-generated. If provided, it must be a valid UUID and unique.

Use cases:

  • Set up workflow stages on a new board
  • Add additional status columns
  • Create custom workflow stages
Authorizations:
personalAccessToken
Request Body schema: application/json
required

Column data to create

id
string <uuid>

Optional UUID for the column (auto-generated if not provided)

name
required
string [ 1 .. 255 ] characters

Name of the column

board_id
required
string <uuid>

ID of the board to add this column to

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Column 1",
  • "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create a card in a column

Creates a new card representing a task on a kanban board column.

Cards connect tasks to board columns, allowing visual workflow management. Each task can only appear once per board but can appear on multiple different boards.

Authentication required: Yes (Bearer token)

Permissions:

  • User must have access to the board
  • User must have permission to create cards for the specified task

UUID Handling: The id field is optional. If not provided, a UUID will be auto-generated. If provided, it must be a valid UUID and unique.

Validation:

  • target_type currently only supports "task"
  • target_id must reference an existing task
  • Task cannot already have a card in the same column
  • Column must exist and belong to an accessible board

Use cases:

  • Add task to a workflow board
  • Track task through different stages
  • Visualize task status on kanban boards
Authorizations:
personalAccessToken
Request Body schema: application/json
required

Card data to create

id
string <uuid>

Optional UUID for the card (auto-generated if not provided)

column_id
required
string <uuid>

ID of the column to place the card in

target_type
required
string
Value: "task"

Type of resource the card represents (currently only task is supported)

target_id
required
integer

ID of the task to create a card for

sort
integer

Sort order within the column

Responses

Request samples

Content type
application/json
Example
{
  • "column_id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
  • "target_type": "task",
  • "target_id": 12345678,
  • "sort": 1
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get health reports for boards

Generates health metrics for one or more boards, analyzing task status and completion percentages.

Authentication required: Yes (Bearer token)

Permissions: User must have access to all specified boards

Health Metrics:

  • On Schedule: Tasks progressing as expected
  • Overdue: Tasks past their end date and not 100% complete
  • Behind: Tasks that started but are behind expected progress
  • Upcoming: Tasks not yet started
  • Percent Complete: Overall completion (weighted by task duration)

Calculation: For each board, the endpoint:

  1. Retrieves all cards and their associated tasks
  2. Analyzes each task's dates and progress
  3. Compares actual vs expected progress based on current date
  4. Categorizes tasks into health status buckets

Response: Returns an array of health report objects, one for each requested board.

Authorizations:
personalAccessToken
query Parameters
ids[]
Array of strings <uuid> [ items <uuid > ]
Example: ids[]=443c80e4-72dc-4363-afd8-b58e6d866b63

Array of board IDs (UUIDs) to generate health reports for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List boards for a project

Retrieves all boards associated with a project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Response: Returns an array of board objects with columns, cards, and user information.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a board for a project

Creates a new board for the project with the specified columns. Each task in the project automatically gets a card created on the first column.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

One Board Per Project: A project can only have one board. If a board already exists, this endpoint will return a 422 error.

Columns: At least one column must be provided. Each column can have:

  • A name
  • Auto-move cards setting (automatically move cards based on task progress)
  • Auto-set task progress (automatically set task progress when card is moved to this column)

Auto Card Creation: When the board is created, a card is automatically created for each task in the project, sorted by WBS and placed in the first column.

Response: Returns the newly created board with all columns and auto-generated cards.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
id
string <uuid>

Optional UUID for the board (auto-generated if not provided)

required
Array of objects non-empty

Array of columns to create for the board (at least one required)

Array (non-empty)
name
required
string [ 1 .. 255 ] characters

Name of the column

auto_move_cards
required
boolean

Whether to automatically move cards to this column based on task progress

auto_set_task_progress
required
integer or null [ 0 .. 100 ]

Automatically set task progress to this percentage when card is in this column (0-100, or null for no auto-set)

Responses

Request samples

Content type
application/json
{
  • "columns": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
  • "name": "Development Board",
  • "company_id": 123456,
  • "status": "active",
  • "user_id": 123,
  • "created_at": "2024-01-10T09:00:00Z",
  • "is_starred": true
}

bookmarks

Manage your list of in-app bookmarks

List all bookmarks

Retrieves all bookmarks for the authenticated user.

Bookmarks allow users to save frequently accessed URLs for quick navigation within the TeamGantt application. Each user has their own set of bookmarks.

Authentication required: Yes (Bearer token)

Permissions: Returns only bookmarks belonging to the current user

Use cases:

  • Quick access to frequently used views
  • Save custom filter combinations
  • Bookmark specific project pages
Authorizations:
personalAccessToken

Responses

Response samples

Content type
application/json
{}

Create a bookmark

Creates a new bookmark for the authenticated user.

Bookmarks save URL locations for quick access. The URL should be a valid TeamGantt application URL.

Authentication required: Yes (Bearer token)

Validation:

  • Name: Required, max 100 characters
  • URL: Required, must be valid URL format, max 2048 characters

Use cases:

  • Save custom filtered views
  • Bookmark frequently accessed projects
  • Quick access to specific task lists
Authorizations:
personalAccessToken
Request Body schema: application/json
required

Bookmark data to create

name
required
string [ 1 .. 100 ] characters

Display name for the bookmark

url
required
string <uri> <= 2048 characters

URL to bookmark

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
{}

Get a specific bookmark

Retrieves details of a single bookmark by its ID.

Authentication required: Yes (Bearer token)

Permissions: User can only access their own bookmarks

Authorizations:
personalAccessToken
path Parameters
bookmarkId
required
integer >= 1
Example: 12345

Unique identifier of the bookmark

Responses

Response samples

Content type
application/json
{}

Update a bookmark

Updates one or more properties of an existing bookmark.

This endpoint supports partial updates - only include the fields you want to change. You can update the display name, the URL, or both.

Authentication required: Yes (Bearer token)

Permissions: User can only update their own bookmarks

Validation:

  • Name: If provided, max 100 characters
  • URL: If provided, must be valid URL format
Authorizations:
personalAccessToken
path Parameters
bookmarkId
required
integer >= 1
Example: 12345

Unique identifier of the bookmark

Request Body schema: application/json
required

Fields to update (partial update supported)

name
string [ 1 .. 100 ] characters

Updated display name

url
string <uri> <= 2048 characters

Updated URL

Responses

Request samples

Content type
application/json
Example
{
  • "name": "My Tasks - Updated"
}

Response samples

Content type
application/json
{}

Delete a bookmark

Permanently deletes a bookmark.

Authentication required: Yes (Bearer token)

Permissions: User can only delete their own bookmarks

Warning: This action cannot be undone.

Authorizations:
personalAccessToken
path Parameters
bookmarkId
required
integer >= 1
Example: 12345

Unique identifier of the bookmark

Responses

Response samples

Content type
application/json
{
  • "message": "Bookmark deleted successfully"
}

comments

Manage comments and notes on tasks, groups, or projects

List comments for a resource

Retrieves all comments and notes associated with a specific task, group, or project.

Comments are returned in reverse chronological order (newest first), with pinned comments appearing at the top of the list regardless of creation date.

Authentication required: Yes (Bearer token)

Permissions: User must have read access to the target resource

Authorizations:
personalAccessToken
path Parameters
target
required
string
Enum: "tasks" "groups" "projects"
Example: tasks

The type of resource the comment is associated with

targetId
required
integer >= 1
Example: 12345

Unique identifier of the target resource (task, group, or project)

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination (starts at 1)

per_page
integer [ 1 .. 100 ]
Default: 20
Example: per_page=20

Number of comments to return per page

type
string
Enum: "comment" "note"
Example: type=comment

Filter comments by type

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a new comment

Creates a new comment or note on a task, group, or project.

Comments can optionally include references to already-uploaded documents. Documents must be uploaded to the target resource before they can be attached to a comment.

Authentication required: Yes (Bearer token)

Permissions: User must have write access to the target resource

Authorizations:
personalAccessToken
path Parameters
target
required
string
Enum: "tasks" "groups" "projects"
Example: tasks

The type of resource the comment is associated with

targetId
required
integer >= 1
Example: 12345

Unique identifier of the target resource (task, group, or project)

Request Body schema: application/json
required

Comment data to create

message
required
string [ 1 .. 10000 ] characters

The comment body text

type
string
Default: "comment"
Enum: "comment" "note"

The type of comment, either 'note' or 'comment'. Defaults to 'comment' if not specified.

attached_documents
string^[0-9]+(,[0-9]+)*$

Comma-separated list of document version IDs. These documents must already be uploaded to the target to link them to a comment.

users_emailed
Array of integers

Array of user IDs to notify via email about this comment (for @mentions)

Responses

Request samples

Content type
application/json
Example
{
  • "message": "Here is a simple comment.",
  • "type": "comment"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "Comment created successfully"
}

Update an existing comment

Updates the message text of an existing comment or note.

Only the user who created the comment, or users with admin permissions on the target resource, can update a comment.

Authentication required: Yes (Bearer token)

Permissions: Must be the comment author or have admin access to the target resource

Authorizations:
personalAccessToken
path Parameters
target
required
string
Enum: "tasks" "groups" "projects"
Example: tasks

The type of resource the comment is associated with

targetId
required
integer >= 1
Example: 12345

Unique identifier of the target resource (task, group, or project)

commentId
required
integer >= 1
Example: 54321

Unique identifier of the comment

Request Body schema: application/json
required

Updated comment data

message
required
string [ 1 .. 10000 ] characters

The updated comment text

attached_documents
string^[0-9]+(,[0-9]+)*$

Comma-separated list of document version IDs to update the comment's attached documents

Responses

Request samples

Content type
application/json
{
  • "message": "Here is an updated comment with corrected information."
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "Comment updated successfully"
}

Delete a comment

Permanently deletes a comment or note from a task, group, or project.

Only the user who created the comment, or users with admin permissions on the target resource, can delete a comment. This action cannot be undone.

Authentication required: Yes (Bearer token)

Permissions: Must be the comment author or have admin access to the target resource

Authorizations:
personalAccessToken
path Parameters
target
required
string
Enum: "tasks" "groups" "projects"
Example: tasks

The type of resource the comment is associated with

targetId
required
integer >= 1
Example: 12345

Unique identifier of the target resource (task, group, or project)

commentId
required
integer >= 1
Example: 54321

Unique identifier of the comment

Responses

Response samples

Content type
application/json
{
  • "message": "Comment deleted successfully",
  • "data": {
    }
}

Pin or unpin a comment

Pins or unpins a comment to the top of the comment list for a task, group, or project.

Pinned comments appear at the top of the comment list regardless of when they were created, making important information easily visible. Multiple comments can be pinned to the same resource.

Authentication required: Yes (Bearer token)

Permissions: User must have write access to the target resource

Authorizations:
personalAccessToken
path Parameters
target
required
string
Enum: "tasks" "groups" "projects"
Example: tasks

The type of resource the comment is associated with

targetId
required
integer >= 1
Example: 12345

Unique identifier of the target resource (task, group, or project)

commentId
required
integer >= 1
Example: 54321

Unique identifier of the comment

Request Body schema: application/json
required

Pin status to set

pinned
required
boolean

Set to true to pin the comment, false to unpin it

Responses

Request samples

Content type
application/json
Example
{
  • "pinned": true
}

Response samples

Content type
application/json
Example
{
  • "data": {
    },
  • "message": "Comment pinned successfully"
}

companies

Manage your company and associated resources

List company users

Retrieves all users in a company.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Invite a user to the company

Invites a new user to join the company or adds an existing user.

Authentication required: Yes (Bearer token)

Permissions: User must have edit access; manager/account_holder requires manage access

Validation: Either provide first_name/last_name OR name field

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Request Body schema: application/json
required
email_address
required
string <email>

Email address of the user to invite

first_name
string

First name of the user

last_name
string

Last name of the user

name
string

Full name (alternative to first_name/last_name)

permissions
required
string
Enum: "basic" "edit" "manager" "account_holder" "guest" "collaborator"

Permission level to grant

send_invite
boolean
Default: true

Whether to send invitation email

Responses

Request samples

Content type
application/json
Example
{
  • "email_address": "user@example.com",
  • "first_name": "John",
  • "last_name": "Smith",
  • "permissions": "basic",
  • "send_invite": false
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a company user

Retrieves details of a specific user in the company.

Authentication required: Yes (Bearer token)

Permissions: User must have manage access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

userId
required
integer >= 1
Example: 123

Unique identifier of the user

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a company user

Updates user information and permissions. Supports partial updates.

Authentication required: Yes (Bearer token)

Permissions: User must have manage access; cannot update own permissions/status

Validation: Email can only be updated for pending users

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

userId
required
integer >= 1
Example: 123

Unique identifier of the user

Request Body schema: application/json
required
first_name
string

Updated first name

last_name
string

Updated last name

email_address
string <email>

Updated email (only for pending users)

permissions
string
Enum: "basic" "edit" "manager" "account_holder" "guest" "collaborator"

Updated permission level

is_disabled
boolean

Whether to disable the user

Responses

Request samples

Content type
application/json
{
  • "permissions": "edit",
  • "email_address": "example@example.com"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Remove a user from the company

Removes a user from the company.

Authentication required: Yes (Bearer token)

Permissions: User must have manage access; cannot remove self

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

userId
required
integer >= 1
Example: 123

Unique identifier of the user

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get all resources for a company

Retrieves all resources including users, company resources, and project resources.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Responses

Response samples

Content type
application/json
{
  • "user_resources": [
    ],
  • "company_resources": [
    ],
  • "project_resources": [
    ]
}

List company resources

Retrieves all company-level resources (equipment, rooms, etc.).

Authentication required: Yes (Bearer token)

Permissions: User must have access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a company resource

Creates a new company-level resource.

Authentication required: Yes (Bearer token)

Permissions: User must have edit access to the company

Limits: Company must not have reached resource limit

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Request Body schema: application/json
required
name
required
string non-empty

Name of the resource

Responses

Request samples

Content type
application/json
{
  • "name": "My Company"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a company resource

Updates a company resource name.

Authentication required: Yes (Bearer token)

Permissions: User must have edit access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

resourceId
required
integer >= 1
Example: 1000

Unique identifier of the resource assigned to a task

Request Body schema: application/json
required
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "Example"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a company resource

Permanently deletes a company resource.

Authentication required: Yes (Bearer token)

Permissions: User must have edit access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

resourceId
required
integer >= 1
Example: 1000

Unique identifier of the resource assigned to a task

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

List project resources for a company

Retrieves all project-level resources associated with the company.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List company holidays

Retrieves all holidays for a company, optionally filtered by year.

Holidays are non-working days that affect project scheduling.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

query Parameters
year
string^\d{4}$
Example: year=2020

Filter by year (YYYY format)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a company holiday

Creates a new holiday for the company.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the company

Validation: Year can be YYYY format or "*" for recurring annual holidays

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

query Parameters
year
string^\d{4}$
Example: year=2020

Filter by year (YYYY format)

Request Body schema: application/json
required
name
string

Name of the holiday (defaults to "Unnamed holiday" if not provided)

year
required
string

Year (YYYY format) or "*" for recurring annual holiday

month
required
integer [ 1 .. 12 ]

Month (1-12)

day
required
integer [ 1 .. 31 ]

Day of the month (1-31)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Christmas",
  • "year": "2025",
  • "month": 12,
  • "day": 25
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a company holiday

Permanently deletes a holiday from the company.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

holidayId
required
integer >= 1
Example: 12345

Unique identifier of the holiday

query Parameters
year
string^\d{4}$
Example: year=2020

Filter by year (YYYY format)

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

List note templates

Retrieves all note templates for a company.

Authentication required: Yes (Bearer token)

Permissions: User must have view permissions on the company

Filtering: Returns both public templates and private templates created by the current user.

Response: Returns an array of note templates sorted by name.

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create note template

Creates a new note template for a company.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the company

Fields:

  • name: Template name (required if note is not provided)
  • note: Template content (required if name is not provided)
  • is_private: Whether the template is private to the creator (defaults to false)

Response: Returns the newly created note template.

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Request Body schema: application/json
required
name
string

Template name (required if note is not provided)

note
string

Template content (required if name is not provided)

is_private
boolean
Default: false

Whether the template is private to the creator

Responses

Request samples

Content type
application/json
{
  • "name": "Standard Meeting Notes",
  • "note": "Meeting Date: {{date}}\nAttendees: {{attendees}}\nNotes:",
  • "is_private": false
}

Response samples

Content type
application/json
{
  • "id": "template-abc-123",
  • "company_id": 123456,
  • "name": "Standard Meeting Notes",
  • "note": "Meeting Date: {{date}}\nAttendees: {{attendees}}\nNotes:",
  • "is_private": false,
  • "created_by": { },
  • "updated_by": { },
  • "created_at": "2024-01-15T10:30:00Z",
  • "updated_at": "2024-01-20T14:45:00Z"
}

Update note template

Updates an existing note template.

Authentication required: Yes (Bearer token)

Permissions:

  • User must have manage permissions on the company
  • User must have edit permissions on the template (or be the creator if private)

Updateable Fields:

  • name: Template name
  • note: Template content
  • is_private: Whether the template is private

Response: Returns the updated note template.

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

noteTemplateId
required
string
Example: template-abc-123

Unique identifier of the note template

Request Body schema: application/json
required
name
string

Template name

note
string

Template content

is_private
boolean

Whether the template is private to the creator

Responses

Request samples

Content type
application/json
{
  • "name": "Updated Meeting Notes",
  • "note": "Meeting Date: {{date}}\nAttendees: {{attendees}}\nNotes:\n{{notes}}",
  • "is_private": false
}

Response samples

Content type
application/json
{
  • "id": "template-abc-123",
  • "company_id": 123456,
  • "name": "Standard Meeting Notes",
  • "note": "Meeting Date: {{date}}\nAttendees: {{attendees}}\nNotes:",
  • "is_private": false,
  • "created_by": { },
  • "updated_by": { },
  • "created_at": "2024-01-15T10:30:00Z",
  • "updated_at": "2024-01-20T14:45:00Z"
}

Delete note template

Permanently deletes a note template.

Authentication required: Yes (Bearer token)

Permissions:

  • User must have manage permissions on the company
  • User must have delete permissions on the template (or be the creator if private)

Warning: This operation cannot be undone.

Response: Returns 204 No Content on success.

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

noteTemplateId
required
string
Example: template-abc-123

Unique identifier of the note template

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Create share key

Creates a share key for a company that can be used to grant public access to projects.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the company or be authorized to create share keys

Share Keys: Share keys allow public access to specific projects without requiring authentication. They are useful for sharing project views with external stakeholders.

Response: Returns the newly created share key.

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Request Body schema: application/json
required
scopes
required
Array of strings non-empty
Items Value: "project.view"

Array of scopes/permissions for the share key

object

Resource groups to include in the share key

projects
Array of integers non-empty

Array of project IDs to include

expiration_date
string <date>

Optional expiration date for the share key (YYYY-MM-DD format, must be after today)

meta
string <json>

Optional JSON metadata

Responses

Request samples

Content type
application/json
{
  • "scopes": [
    ],
  • "resources": {
    },
  • "expiration_date": "2024-12-31",
  • "meta": "{\"description\": \"Public project view\"}"
}

Response samples

Content type
application/json
{
  • "key": "abc123def456ghi789",
  • "scopes": [
    ],
  • "expiration_date": "2024-12-31T23:59:59Z",
  • "resources": { },
  • "meta": { },
  • "last_used_at": "2024-01-15T10:30:00Z"
}

Get company details

Retrieves detailed information about a specific company.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update company information

Updates company information. Supports partial updates.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Request Body schema: application/json
required
name
string

Updated company name

Responses

Request samples

Content type
application/json
{
  • "name": "Example Company Name"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List company projects

Retrieves all projects within a company.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List folders for a company

Retrieves all folders accessible to the user within a company.

Folders organize projects and boards for better navigation and management.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a folder

Creates a new folder for organizing projects and boards.

Folder names must be unique within the company.

Authentication required: Yes (Bearer token)

Permissions: User must have edit access to the company

Validation: Name max 100 characters, must be unique per company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Request Body schema: application/json
required
id
string <uuid>

Optional UUID for the folder (auto-generated if not provided)

name
required
string [ 1 .. 100 ] characters

Name of the folder (must be unique within the company)

is_starred
boolean
Default: false

Whether to star the folder for the current user

Responses

Request samples

Content type
application/json
{
  • "name": "Example Folder Name",
  • "is_starred": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List company teams

Retrieves all teams in a company.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the company; filtered by team read permission

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a team

Creates a new team within the company.

Team names must be unique within the company.

Authentication required: Yes (Bearer token)

Permissions: User must have manage access to the company

Validation: Name max 100 characters, must be unique per company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Request Body schema: application/json
required
id
string <uuid>

Optional UUID for the team (auto-generated if not provided)

name
required
string [ 1 .. 100 ] characters

Name of the team (must be unique within company)

Responses

Request samples

Content type
application/json
{
  • "name": "Development Team"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get resource options for a company

Retrieves available resource options for the company.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Responses

Response samples

Content type
application/json
{ }

List company resources (alias)

Retrieves company resources. Alias endpoint.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a company resource (alias)

Creates a new company resource. Alias endpoint.

Authentication required: Yes (Bearer token)

Permissions: User must have edit access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Request Body schema: application/json
required
name
required
string non-empty

Name of the resource

Responses

Request samples

Content type
application/json
{
  • "name": "Resource Name"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a company resource (alias)

Updates a company resource.

Authentication required: Yes (Bearer token)

Permissions: User must have edit access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

resourceId
required
integer >= 1
Example: 1000

Unique identifier of the resource assigned to a task

Request Body schema: application/json
required
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "Testing02"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a company resource (alias)

Permanently deletes a company resource.

Authentication required: Yes (Bearer token)

Permissions: User must have edit access to the company

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

resourceId
required
integer >= 1
Example: 1000

Unique identifier of the resource assigned to a task

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

costs

Get cost data for a company, project, or set of projects

Get monthly costs for projects or companies

Retrieves monthly cost data for specified projects and/or companies over a date range.

Authentication required: Yes (Bearer token)

Permissions: User must have access to at least one of the specified projects or companies. The user's company must have the COST_TAB feature enabled.

Date Range: Both start_date and end_date are required query parameters.

Filtering:

  • Provide project_ids[] to get costs for specific projects
  • Provide company_ids[] to get costs for all projects within those companies
  • You can provide both filters simultaneously
  • At least one filter must be provided, or the request will return all accessible projects

Response: Returns an array of cost objects, each representing either a project or company with monthly cost breakdowns.

Cost Calculation: Costs are calculated based on task costs and distributed across months according to task duration and cost load mode (front, back, or even).

Authorizations:
personalAccessToken
query Parameters
start_date
required
string <date>
Example: start_date=2024-01-01

Start date for cost calculation (ISO 8601 format YYYY-MM-DD)

end_date
required
string <date>
Example: end_date=2024-12-31

End date for cost calculation (ISO 8601 format YYYY-MM-DD)

project_ids[]
Array of integers
Example: project_ids[]=920883&project_ids[]=920884

Array of project IDs to filter tasks. Can be specified multiple times for multiple projects.

company_ids[]
Array of integers
Example: company_ids[]=123456&company_ids[]=123457

Array of company IDs to filter costs. Can be specified multiple times for multiple companies.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

current_user

Get information about the current user

Get information about the currently authenticated user

Retrieves detailed information about the currently authenticated user.

Authentication required: Yes (Bearer token)

Response includes:

  • User profile information (name, email, timezone, profile picture)
  • All companies the user belongs to (with permissions, features, plans)
  • User integrations (Basecamp, Trello, etc.)
  • Notification preferences (email and mobile)
  • User preferences and settings
  • Metrics and statistics
  • Welcome survey data (if available)

Company Data: The response includes nested company data with features, plans, limitations, and subscriptions. This provides comprehensive context about the user's access levels and capabilities across all their companies.

Authorizations:
personalAccessToken

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "email_address": "user@example.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "pic": "https://example.com/assets/user_pic/?text=JD",
  • "time_zone": "-05:00",
  • "today_date": "2024-01-15",
  • "status": "active",
  • "daily_email_hour": 9,
  • "companies": [
    ],
  • "integrations": [ ],
  • "preferences": { },
  • "notifications": { },
  • "mobile_notifications": { },
  • "created_at": "2024-01-01T00:00:00Z"
}

discussions

Manage task, group, and project discussions

Get discussions across projects

Retrieves a list of discussions (tasks, groups, or projects with comments) across all accessible projects.

Authentication required: Yes (Bearer token)

Permissions: User must have access to at least one active project

Filtering: Use query parameters to filter discussions:

  • is_unread: Only discussions with unread comments
  • is_mentioned: Only discussions where the current user is mentioned
  • has_unread_mention: Only discussions with unread mentions of current user
  • is_my_task: Only discussions for tasks assigned to current user
  • is_starred: Only discussions for starred resources
  • project_id[]: Filter by specific project IDs
  • offset: Pagination offset (default: 0)
  • limit: Maximum number of discussions to return (default: 500, max: 500)

Response: Returns an object with unread counts and an array of discussion objects. Each discussion includes metadata about the resource, comment information, and unread status.

Sorting: Discussions are sorted by most recent comment date (descending).

Authorizations:
personalAccessToken
query Parameters
offset
integer >= 0
Default: 0

Offset for pagination of discussions

limit
integer [ 1 .. 500 ]
Default: 500
Example: limit=500

Maximum number of discussions to return

is_unread
boolean
Example: is_unread=true

Filter discussions to only unread items

is_mentioned
boolean
Example: is_mentioned=true

Filter discussions to only items where current user is mentioned

has_unread_mention
boolean
Example: has_unread_mention=true

Filter discussions to only items with unread mentions of current user

is_my_task
boolean
Example: is_my_task=true

Filter discussions to only tasks assigned to current user

is_starred
boolean
Example: is_starred=true

Filter discussions to only starred items

project_id[]
Array of integers
Example: project_id[]=920883&project_id[]=920884

Array of project IDs to filter discussions. Can be specified multiple times.

Responses

Response samples

Content type
application/json
{
  • "unread_count": 5,
  • "unread_mention_count": 2,
  • "discussions": [
    ]
}

documents

Document management endpoints

List documents across projects

Retrieves all documents attached to tasks, groups, or projects across accessible projects.

Authentication required: Yes (Bearer token)

Permissions: User must have access to at least one project

Filtering: Use project_ids[] query parameter to filter documents by specific projects. If not provided, returns documents from all accessible projects.

Response: Returns an array of document objects. Each document includes metadata such as name, size, MIME type, upload information, and download URLs.

Document Versions: Documents may have multiple versions. Each version is tracked separately with version numbers and timestamps.

Authorizations:
personalAccessToken
query Parameters
project_ids[]
Array of integers
Example: project_ids[]=920883&project_ids[]=920884

Array of project IDs to filter documents. Can be specified multiple times.

Responses

Response samples

Content type
application/json
[]

downloads

Download endpoints

Download a document file

Downloads the binary file content for a specific document attached to a task.

This endpoint returns the raw file data with appropriate headers for file download. The response includes Content-Disposition header to suggest the filename for saving.

Authentication required: Yes (Bearer token)

Rate limiting: Standard rate limits apply

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

documentId
required
integer >= 1
Example: 67890

Unique identifier of the document

query Parameters
q
string [ 1 .. 255 ] characters
Example: q=meeting notes

Optional search/filter query string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

groups

Group management endpoints

Create a new group

Creates a new group (or subgroup) within a project.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Group Types:

  • Root-level groups: Set parent_group_id to null or omit it
  • Subgroups: Set parent_group_id to an existing group ID

Sort Order: If sort is not provided, the group will be placed at the end of the list.

Collapsed State: The is_collapsed setting is user-specific and defaults to false if not provided.

Authorizations:
personalAccessToken
Request Body schema: application/json
required
project_id
required
integer

ID of the project this group belongs to

parent_group_id
integer or null

ID of the parent group (null for root-level groups)

name
required
string [ 1 .. 255 ] characters

Name of the group

sort
integer

Sort order of the group

is_collapsed
boolean
Default: false

Whether the group is collapsed for the current user (defaults to false)

Responses

Request samples

Content type
application/json
{
  • "project_id": 234567,
  • "name": "My First Group",
  • "parent_group_id": null,
  • "sort": 1,
  • "is_collapsed": false
}

Response samples

Content type
application/json
{
  • "id": 456789,
  • "name": "My First Group",
  • "project_id": 234567,
  • "parent_group_id": null,
  • "sort": 1,
  • "is_collapsed": false,
  • "children": [ ]
}

Bulk update multiple groups

Updates multiple groups in a single request. All updates are performed within a transaction - if any update fails, the entire operation is rolled back.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on all projects containing the groups being updated

Transaction Safety: This operation is atomic. If any group update fails, none of the changes are applied.

Update Fields: Each group update can include:

  • project_id: Move group to a different project (requires edit permission on both projects)
  • parent_group_id: Change parent group (must be in same project)
  • name: Update group name
  • sort: Update sort order
  • is_collapsed: Update collapsed state (user-specific)
Authorizations:
personalAccessToken
Request Body schema: application/json
required
required
Array of objects

Array of group updates

Array
id
required
integer

Group ID

parent_group_id
required
integer or null

ID of the parent group

name
required
string

Group name

sort
required
integer

Sort order

is_collapsed
required
boolean

Whether the group is collapsed

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

List groups by project

Retrieves all groups for the specified projects.

Authentication required: Yes (Bearer token)

Permissions: User must have access to at least one of the specified projects

Required: At least one project_ids[] must be provided

Nested Structure: By default, groups are returned with nested children (tasks and subgroups). Use flatten_children=true to get a flat list instead.

Response: Returns an array of group objects. Each group includes its children (tasks and subgroups) in a nested structure unless flatten_children=true is specified.

Authorizations:
personalAccessToken
query Parameters
project_ids[]
required
Array of integers
Example: project_ids[]=123456

Array of project IDs to fetch groups for. Can be specified multiple times.

flatten_children
boolean
Example: flatten_children=true

Whether to flatten nested groups into a flat list structure

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a specific group

Retrieves detailed information about a specific group, including its children (tasks and subgroups).

Authentication required: Yes (Bearer token)

Permissions: User must have access to the group's project

Nested Structure: By default, the group's children are returned in a nested structure. Use flatten_children=true to get a flat list instead.

Response: Returns a group object with nested children unless flatten_children=true is specified.

Authorizations:
personalAccessToken
path Parameters
groupId
required
integer >= 1
Example: 12345

Unique identifier of the group

query Parameters
flatten_children
boolean
Example: flatten_children=true

Whether to flatten nested groups into a flat list structure

Responses

Response samples

Content type
application/json
{
  • "id": 456789,
  • "name": "Design Phase",
  • "project_id": 234567,
  • "parent_group_id": null,
  • "sort": 1,
  • "is_collapsed": false,
  • "children": [
    ]
}

Update a group

Updates a group's properties. Supports partial updates - only include the fields you want to change.

Authentication required: Yes (Bearer token)

Permissions:

  • Edit permissions: Can update project_id, parent_group_id, name, sort, and is_collapsed
  • View-only permissions: Can only update is_collapsed (user-specific collapsed state)

Moving Groups:

  • Changing project_id moves the group to a different project (requires edit permission on both projects)
  • Changing parent_group_id moves the group within the same project (new parent must be in the same project)

Validation: The group name cannot be empty. If project_id is changed, the new parent_group_id (if provided) must belong to the new project.

Authorizations:
personalAccessToken
path Parameters
groupId
required
integer >= 1
Example: 12345

Unique identifier of the group

Request Body schema: application/json
required
project_id
integer

ID of the project this group belongs to

parent_group_id
integer or null

ID of the parent group (null for root-level groups)

name
string [ 1 .. 255 ] characters

Name of the group

sort
integer

Sort order of the group

is_collapsed
boolean

Whether the group is collapsed for the current user

Responses

Request samples

Content type
application/json
{
  • "name": "Updated Group Name",
  • "sort": 2
}

Response samples

Content type
application/json
{
  • "id": 456789,
  • "name": "Updated Group Name",
  • "project_id": 234567,
  • "parent_group_id": null,
  • "sort": 2,
  • "is_collapsed": false
}

Delete a group

Permanently deletes a group and all its contents (tasks and subgroups).

Authentication required: Yes (Bearer token)

Permissions: User must have admin or edit permissions on the project

Warning: This operation cannot be undone. All tasks and subgroups within this group will also be deleted.

Response: Returns 204 No Content on success.

Authorizations:
personalAccessToken
path Parameters
groupId
required
integer >= 1
Example: 12345

Unique identifier of the group

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get children of a group

Retrieves the direct children (tasks and subgroups) of a specific group.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the group's project

Nested vs Flat:

  • Default: Returns children in nested structure (groups contain their own children)
  • With is_flat_list=true: Returns a flat list of all descendant tasks and groups

Response: Returns an array of tasks and groups. Each group may contain its own children unless is_flat_list=true is specified.

Authorizations:
personalAccessToken
path Parameters
groupId
required
integer >= 1
Example: 12345

Unique identifier of the group

query Parameters
is_flat_list
boolean
Example: is_flat_list=true

Return children as a flat list instead of nested structure

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Duplicate a group

Creates a duplicate of a group, including all its tasks, subgroups, and notes. The duplicate is created within the same project.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

What Gets Copied:

  • Group structure (nested groups and subgroups)
  • All tasks within the group
  • Task dependencies (between duplicated tasks)
  • Note-type comments (standard comments are not copied)

What Doesn't Get Copied:

  • Standard comments (non-note comments)
  • Document attachments
  • Resource assignments
  • Time blocks

Nested Structure: By default, the duplicated group's children are returned in a nested structure. Use flatten_children=true to get a flat list instead.

Sort Order: The duplicated group is placed immediately after the original group (sort order + 1).

Response: Returns the newly created group with its children (unless flatten_children=true).

Authorizations:
personalAccessToken
path Parameters
groupId
required
integer >= 1
Example: 12345

Unique identifier of the group

query Parameters
flatten_children
boolean
Example: flatten_children=true

Whether to flatten nested groups into a flat list structure

Responses

Response samples

Content type
application/json
{
  • "id": 456791,
  • "name": "Design Phase",
  • "project_id": 234567,
  • "parent_group_id": null,
  • "sort": 2,
  • "is_collapsed": false,
  • "children": [
    ]
}

Get history/audit log for a group

Retrieves the history/audit log entries for a specific group, showing all changes made to the group over time.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the group's project

History Entries: Each entry records:

  • What was changed (e.g., "name", "parent_group_id", "sort")
  • The new value or description of the change
  • Who made the change
  • When the change occurred

Pagination: Use offset and limit query parameters to paginate through history entries.

Response: Returns a paginated list of history entries, sorted by most recent first.

Authorizations:
personalAccessToken
path Parameters
groupId
required
integer >= 1
Example: 12345

Unique identifier of the group

query Parameters
offset
integer >= 0
Default: 0

Offset for pagination of history entries

limit
integer [ 1 .. 100 ]
Default: 50
Example: limit=50

Maximum number of history entries to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

operations

Operation endpoints

Execute batch operations

Executes multiple operations (add, update, remove) on various resources in a single request. All operations are performed within a transaction - if any operation fails, the entire batch is rolled back.

Authentication required: Yes (Bearer token)

Transaction Safety: This operation is atomic. If any operation fails, none of the changes are applied.

Operation Types:

  • add: Add items to a relationship (e.g., add cards to a column)
  • update: Update items in a relationship
  • remove: Remove items from a relationship

Resource Types: Operations can be performed on various resource types including:

  • columns, boards, folders (and their relationships like cards)

Reference Structure: Each operation requires:

  • op: The operation type (add, update, remove)
  • ref: Reference to the target resource with id (UUID), type, and optional relationship
  • data: Array of data items for the operation (each with an id UUID)

Response: Returns an array of operation results, one for each operation in the request. Each result indicates success/failure and includes result data or error information.

Validation: Operations are validated before execution. Invalid operation combinations are rejected with a 422 status.

Authorizations:
personalAccessToken
Request Body schema: application/json
required
required
Array of objects (Operation)

Array of operations to perform

Array
op
required
string
Enum: "add" "update" "remove"

Operation type

required
object

Reference to the target resource

required
Array of objects

Array of data items for the operation

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

procurement

Procurement board management endpoints

Get procurement board by company

Retrieves the procurement board for a specific company.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the procurement board

Response: Returns the procurement board with its columns and cards.

Note: Each company can have only one procurement board.

Authorizations:
personalAccessToken
path Parameters
companyId
required
integer >= 1
Example: 123456

Unique identifier of the company

Responses

Response samples

Content type
application/json
{
  • "id": "abc123-def456-ghi789",
  • "company_id": 123456,
  • "lead_days": 30,
  • "project_ids": [
    ],
  • "columns": [
    ]
}

Create procurement board

Creates a new procurement board for a company.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the company

Limitations:

  • Each company can have only one procurement board
  • If a procurement board already exists for the company, returns 409 Conflict

Response: Returns the newly created procurement board.

Note: Cards are automatically synced based on the associated projects after creation.

Authorizations:
personalAccessToken
Request Body schema: application/json
required
company_id
required
integer

ID of the company

lead_days
required
integer >= 1

Number of lead days for procurement planning

project_ids
required
Array of integers

Array of project IDs to associate with the board

Responses

Request samples

Content type
application/json
{
  • "company_id": 123456,
  • "lead_days": 30,
  • "project_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "abc123-def456-ghi789",
  • "company_id": 123456,
  • "lead_days": 30,
  • "project_ids": [
    ],
  • "columns": [
    ]
}

Get procurement board

Retrieves a specific procurement board by ID with its columns and cards.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the procurement board

Response: Returns the procurement board with its columns and cards loaded.

Authorizations:
personalAccessToken
path Parameters
procurementBoardId
required
string
Example: abc123-def456-ghi789

Unique identifier of the procurement board

Responses

Response samples

Content type
application/json
{
  • "id": "abc123-def456-ghi789",
  • "company_id": 123456,
  • "lead_days": 30,
  • "project_ids": [
    ],
  • "columns": [
    ]
}

Update procurement board

Updates a procurement board's settings.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the company

Updateable Fields:

  • lead_days: Number of lead days for procurement planning
  • project_ids: Array of project IDs to associate with the board (replaces existing projects)

Note: When updating project_ids, the existing projects are replaced. Cards are automatically synced after update.

Authorizations:
personalAccessToken
path Parameters
procurementBoardId
required
string
Example: abc123-def456-ghi789

Unique identifier of the procurement board

Request Body schema: application/json
required
lead_days
integer >= 1

Number of lead days for procurement planning

project_ids
Array of integers

Array of project IDs to associate with the board (replaces existing)

Responses

Request samples

Content type
application/json
{
  • "lead_days": 30,
  • "project_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "abc123-def456-ghi789",
  • "company_id": 123456,
  • "lead_days": 30,
  • "project_ids": [
    ],
  • "columns": [
    ]
}

Add projects to procurement board

Adds one or more projects to a procurement board.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the procurement board's company

Behavior: Projects are added without removing existing projects. Cards are automatically synced after adding projects.

Response: Returns 201 Created on success.

Authorizations:
personalAccessToken
path Parameters
procurementBoardId
required
string
Example: abc123-def456-ghi789

Unique identifier of the procurement board

Request Body schema: application/json
required
project_ids
required
Array of integers

Array of project IDs to add to the board

Responses

Request samples

Content type
application/json
{
  • "project_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Remove project from procurement board

Removes a project from a procurement board.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the procurement board's company

Behavior: Cards are automatically synced after removing the project.

Response: Returns 204 No Content on success.

Authorizations:
personalAccessToken
path Parameters
procurementBoardId
required
string
Example: abc123-def456-ghi789

Unique identifier of the procurement board

procurementBoardProjectId
required
integer
Example: 12345

ID of the procurement board project relationship

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Bulk remove projects from procurement board

Removes multiple projects from a procurement board in a single operation.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the procurement board's company

Behavior: Cards are automatically synced after removing projects.

Response: Returns 204 No Content on success.

Authorizations:
personalAccessToken
path Parameters
procurementBoardId
required
string
Example: abc123-def456-ghi789

Unique identifier of the procurement board

Request Body schema: application/json
required
project_ids
required
Array of integers

Array of project IDs to remove from the board

Responses

Request samples

Content type
application/json
{
  • "project_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

List procurement board users

Retrieves all users who have access to a procurement board.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the company

Response: Returns an array of user objects.

Authorizations:
personalAccessToken
path Parameters
procurementBoardId
required
string
Example: abc123-def456-ghi789

Unique identifier of the procurement board

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add user to procurement board

Adds a user to a procurement board.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the company

Requirements:

  • User must be a member of the company
  • User cannot be a guest or collaborator
  • User must not already be on the board

Optional: Set send_invite: true to send an invitation email to the user.

Authorizations:
personalAccessToken
path Parameters
procurementBoardId
required
string
Example: abc123-def456-ghi789

Unique identifier of the procurement board

Request Body schema: application/json
required
user_id
required
integer

ID of the user to add

message
string

Optional message to include in invitation email

send_invite
boolean
Default: false

Whether to send an invitation email

Responses

Request samples

Content type
application/json
{
  • "user_id": 123,
  • "message": "You've been added to the procurement board",
  • "send_invite": true
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Remove user from procurement board

Removes a user from a procurement board.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the company

Response: Returns 204 No Content on success.

Authorizations:
personalAccessToken
path Parameters
procurementBoardId
required
string
Example: abc123-def456-ghi789

Unique identifier of the procurement board

userId
required
integer >= 1
Example: 123

Unique identifier of the user

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Send invitation emails to procurement board users

Sends invitation emails to one or more users who are already on the procurement board.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the company

Requirements: All users must already be members of the procurement board.

Response: Returns 204 No Content on success.

Authorizations:
personalAccessToken
path Parameters
procurementBoardId
required
string
Example: abc123-def456-ghi789

Unique identifier of the procurement board

Request Body schema: application/json
required
users
required
Array of integers

Array of user IDs to send invitations to

message
string

Optional message to include in invitation email

Responses

Request samples

Content type
application/json
{
  • "users": [
    ],
  • "message": "You've been invited to the procurement board"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

List procurement board teams

Retrieves all teams that have access to a procurement board.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the company

Response: Returns an array of team objects.

Authorizations:
personalAccessToken
path Parameters
procurementBoardId
required
string
Example: abc123-def456-ghi789

Unique identifier of the procurement board

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add team to procurement board

Adds a team to a procurement board, granting all team members access.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the company

Requirements:

  • Team must belong to the same company as the procurement board
  • Team must not already be on the board

Optional: Set send_invite: true to send invitation emails to all team members.

Authorizations:
personalAccessToken
path Parameters
procurementBoardId
required
string
Example: abc123-def456-ghi789

Unique identifier of the procurement board

Request Body schema: application/json
required
team_id
required
string <uuid>

ID of the team to add

message
string

Optional message to include in invitation emails

send_invite
boolean
Default: false

Whether to send invitation emails to team members

Responses

Request samples

Content type
application/json
{
  • "team_id": "team-abc-123",
  • "message": "Your team has been added to the procurement board",
  • "send_invite": true
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Remove team from procurement board

Removes a team from a procurement board, revoking access for all team members.

Authentication required: Yes (Bearer token)

Permissions: User must have manage permissions on the company

Response: Returns 204 No Content on success.

Authorizations:
personalAccessToken
path Parameters
procurementBoardId
required
string
Example: abc123-def456-ghi789

Unique identifier of the procurement board

teamId
required
string <uuid>
Example: abc123-def456-ghi789-jkl012

ID of the team to remove

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Update procurement card

Updates a procurement card's position or column.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the procurement board

Updateable Fields:

  • column_id: Move card to a different column
  • sort: Change the sort order of the card

Response: Returns the updated procurement card with material and task information.

Authorizations:
personalAccessToken
path Parameters
procurementCardId
required
string
Example: card-123-def456

Unique identifier of the procurement card

Request Body schema: application/json
required
column_id
string

ID of the column to move the card to

sort
required
integer

Sort order position

Responses

Request samples

Content type
application/json
{
  • "column_id": "col-abc-123",
  • "sort": 5
}

Response samples

Content type
application/json
{
  • "id": "card-123-def456",
  • "board_id": "abc123-def456-ghi789",
  • "column_id": "col-abc-123",
  • "material_id": "mat-123-456",
  • "sort": 5,
  • "material": { },
  • "task": { }
}

projects

Project management endpoints

Update project access permissions

Updates a user's access to a project, including their permission level and color.

Authentication required: Yes (Bearer token)

Permissions:

  • Project admin: Can update permission and color
  • Project editor: Can only update color (not permission)

Permission Restrictions:

  • Only project admins can change permission levels
  • Guest users cannot have their permission changed from "view_only"
  • Permission updates for non-guest users require admin access

Color: The color is used to visually distinguish the user in resource views and Gantt charts.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

accesseId
required
integer >= 1
Example: 7070608

Unique identifier of the project access record

Request Body schema: application/json
required
permission
string
Enum: "admin" "edit" "own_progress" "view_only"

Update the permission level (only project admins can change this)

color
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Update the color assigned to this user

Responses

Request samples

Content type
application/json
{
  • "permission": "edit",
  • "color": "green2"
}

Response samples

Content type
application/json
{
  • "id": 7070608,
  • "project_id": 920883,
  • "company_id": 1000,
  • "user_id": 1960234,
  • "permission": "edit",
  • "status": "Accepted",
  • "color": "green2",
  • "user": {
    }
}

Remove user access from project

Removes a user's access to a project, effectively uninviting them or revoking their access.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Effects:

  • User will no longer see the project in their project list
  • User's resource assignments to tasks in this project will be removed
  • User's comments and history remain intact

Warning: This operation cannot be undone. The user will need to be re-invited to regain access.

Response: Returns 204 No Content on success.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

accesseId
required
integer >= 1
Example: 7070608

Unique identifier of the project access record

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Invite user to project or join project

This endpoint has two modes based on the join query parameter:

Mode 1: Invite User (default) - Invite a user to join the project

  • Requires user_id in request body
  • User must be a member of the project's company
  • Only project admins can invite users
  • Guest users can only be invited to one project at a time
  • Invitation email is sent by default (can be disabled with send_invite: false)

Mode 2: Join Project - Current user joins a project they own but are not yet a member of

  • Add ?join=true query parameter
  • User must be a company account holder
  • User is automatically added with admin permissions
  • No invitation email is sent

Authentication required: Yes (Bearer token)

Permissions:

  • Invite mode: Must be project admin
  • Join mode: Must be company account holder who owns the project
Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

query Parameters
join
string or null
Example: join=true

Set to any truthy value to join the project instead of inviting a user

Request Body schema: application/json
optional

Required for invite mode, optional for join mode

user_id
required
integer

ID of the user to invite to the project

color
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Color to assign to the user for this project (defaults to user's last used color)

custom_message
string <= 1000 characters

Optional custom message to include in the invitation email

send_invite
boolean
Default: true

Whether to send invitation email (defaults to true)

Responses

Request samples

Content type
application/json
{
  • "user_id": 1960234,
  • "color": "blue2",
  • "custom_message": "Join the party!",
  • "send_invite": true
}

Response samples

Content type
application/json
{
  • "id": 7070608,
  • "project_id": 920883,
  • "company_id": 1000,
  • "user_id": 1960234,
  • "permission": "edit",
  • "status": "Pending",
  • "color": "blue2",
  • "custom_message": "Join the party!",
  • "user": {
    }
}

List project accesses

Retrieves all users who have access to the project, including their permission levels and status.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Response: Returns an array of project access objects, each representing a user's access to the project. Includes user information, permission level, invitation status, and assigned color.

Status Values:

  • Pending: User has been invited but has not accepted
  • Accepted: User has accepted and has access to the project
Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Resend project invitation email

Resends the invitation email to a user who has been invited to a project but has not yet accepted.

Authentication required: Yes (Bearer token)

Permissions: User must be a project admin

Use Cases:

  • User didn't receive the original invitation
  • Invitation email was lost or deleted
  • Reminder for pending invitations

Note: This endpoint only works for project accesses with status "Pending". The user must already have been invited to the project.

Email: The invitation email will be sent to the user's registered email address with the project details and an invitation link.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

accesseId
required
integer >= 1
Example: 7070608

Unique identifier of the project access record

Request Body schema: application/json
optional

Request body is deprecated and not used. This endpoint accepts no body.

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": 7070608,
  • "project_id": 920883,
  • "company_id": 1000,
  • "user_id": 1960234,
  • "permission": "edit",
  • "status": "Pending",
  • "color": "blue2",
  • "user": {
    }
}

List boards for a project

Retrieves all boards associated with a project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Response: Returns an array of board objects with columns, cards, and user information.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a board for a project

Creates a new board for the project with the specified columns. Each task in the project automatically gets a card created on the first column.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

One Board Per Project: A project can only have one board. If a board already exists, this endpoint will return a 422 error.

Columns: At least one column must be provided. Each column can have:

  • A name
  • Auto-move cards setting (automatically move cards based on task progress)
  • Auto-set task progress (automatically set task progress when card is moved to this column)

Auto Card Creation: When the board is created, a card is automatically created for each task in the project, sorted by WBS and placed in the first column.

Response: Returns the newly created board with all columns and auto-generated cards.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
id
string <uuid>

Optional UUID for the board (auto-generated if not provided)

required
Array of objects non-empty

Array of columns to create for the board (at least one required)

Array (non-empty)
name
required
string [ 1 .. 255 ] characters

Name of the column

auto_move_cards
required
boolean

Whether to automatically move cards to this column based on task progress

auto_set_task_progress
required
integer or null [ 0 .. 100 ]

Automatically set task progress to this percentage when card is in this column (0-100, or null for no auto-set)

Responses

Request samples

Content type
application/json
{
  • "columns": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
  • "name": "Development Board",
  • "company_id": 123456,
  • "status": "active",
  • "user_id": 123,
  • "created_at": "2024-01-10T09:00:00Z",
  • "is_starred": true
}

List project baselines

Retrieves all baselines for a project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Baselines: Baselines are snapshots of a project's tasks at a specific point in time, useful for tracking changes and comparing current state vs. original plan.

Response: Returns an array of baseline objects with basic information (no task details). Use GET /baselines/{id} to get full baseline with tasks.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create a project baseline

Creates a new baseline for the project, capturing the current state of all tasks.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Feature Required: The project's company must have the BASELINES feature enabled

Baseline Name: If no name is provided, the baseline will be named with the current UTC timestamp (e.g., "2024-01-15 10:30:00").

What Gets Captured:

  • All tasks in the project
  • Task start dates
  • Task end dates
  • Task completion percentages

Response: Returns the newly created baseline (without task details). Use GET /baselines/{id} to retrieve the full baseline with tasks.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
optional
name
string <= 255 characters

Optional name for the baseline (defaults to current UTC timestamp if not provided)

id
string <uuid>

Optional UUID for the baseline (auto-generated if not provided)

Responses

Request samples

Content type
application/json
{
  • "name": "2020-Q1"
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "project_id": 920883,
  • "name": "2020-Q1",
  • "created_at": "2024-01-15T10:30:00Z"
}

Add a team to a project

Adds a team to a project, granting all team members access with the specified permission level.

Authentication required: Yes (Bearer token)

Permissions: User must be a project admin

Team Requirements:

  • Team must belong to the same company as the project
  • Team cannot already be assigned to this project

Invitation Emails: By default, all team members will receive invitation emails. Set send_invite: false to skip sending emails.

Response: Returns the project team assignment with nested team and user information.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
team_id
required
string <uuid>

ID of the team to add

permission
required
string
Enum: "admin" "edit" "own_progress" "view_only"

Permission level to grant the team

message
string or null <= 1000 characters

Optional custom message to include in invitation emails sent to team members

send_invite
boolean
Default: true

Whether to send invitation emails to team members (defaults to true)

Responses

Request samples

Content type
application/json
{
  • "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  • "permission": "admin",
  • "message": "Welcome to the project!",
  • "send_invite": true
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "project_id": 920883,
  • "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  • "permission": "admin",
  • "team": {
    }
}

Get RACI roles for a project

Retrieves all RACI (Responsible, Accountable, Consulted, Informed) role assignments for a project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

RACI Matrix: RACI is a responsibility assignment matrix used to clarify roles:

  • R (Responsible): Does the work
  • A (Accountable): Ultimately answerable for the task
  • C (Consulted): Provides input/advice
  • I (Informed): Kept up-to-date on progress

Response: Returns an array of RACI role assignments showing which users have which roles for each task, group, or project.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create or update RACI role assignment

Creates or updates a RACI role assignment for a user on a target resource (task, group, or project).

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Upsert Behavior: If a RACI assignment already exists for this user+target combination, it will be updated. Otherwise, a new assignment is created.

Roles:

  • Pass an array of role letters: ["R", "A", "C", "I"]
  • Roles are combined into a string (e.g., ["R", "A"] becomes "RA")
  • Pass empty array or null to remove all roles for this user+target
  • Order doesn't matter; roles are normalized

Validation:

  • target_type must be "task", "group", or "project"
  • resource_type must be "user" (currently only users are supported)
  • User (resource_id) must have access to the project
  • Target must exist and belong to the specified project

Response: Returns the created or updated RACI role assignment.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
project_id
required
integer

ID of the project

target_type
required
string
Enum: "task" "group" "project"

Type of target resource

target_id
required
integer

ID of the target resource

resource_type
required
string
Value: "user"

Type of resource (currently only 'user' is supported)

resource_id
required
integer

ID of the resource (user ID)

roles
required
Array of strings or null[ items^[RACI]$ ]
Enum: "R" "A" "C" "I"

Array of RACI role letters (R, A, C, I). Pass empty array or null to remove all roles.

Responses

Request samples

Content type
application/json
Example
{
  • "project_id": 1000,
  • "target_type": "task",
  • "target_id": 12345,
  • "resource_type": "user",
  • "resource_id": 1000,
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 1000,
  • "target_type": "task",
  • "target_id": 12345,
  • "resource_type": "user",
  • "resource_id": 1000,
  • "roles": "RA"
}

Get all available resources for a project

Retrieves all resources that can be assigned to tasks in this project, including users, company resources, and project-specific resources.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Resource Types:

  • User Resources: Users from the company who can be assigned to tasks
  • Company Resources: Company-level resources (equipment, rooms, etc.) available to this project
  • Project Resources: Project-specific resources that only exist within this project

Response: Returns an object with three arrays, one for each resource type.

Use Cases:

  • Populating resource dropdowns in UI
  • Determining which resources can be assigned to tasks
  • Resource planning and allocation
Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
{
  • "user_resources": [
    ],
  • "company_resources": [
    ],
  • "project_resources": [
    ]
}

Get all resources for a project (alias)

Retrieves all resources available for a project. This is an alias for /projects/{projectId}/resource_options.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Response: Returns an object containing three resource types:

  • User resources (users from the company)
  • Company resources (company-level resources)
  • Project resources (project-specific resources)

Note: This endpoint is functionally identical to /projects/{projectId}/resource_options. Use that endpoint instead for consistency.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
{
  • "user_resources": [
    ],
  • "company_resources": [
    ],
  • "project_resources": [
    ]
}

List project-specific resources (labels)

Retrieves all project-specific resources (resources that exist only within this project, not company-wide).

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Response: Returns an array of project resource objects.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a project-specific resource (label)

Creates a new resource specific to this project (not shared with other projects).

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project and company

Resource Limit: Company must not have reached the maximum resources limit for their plan.

Use Cases:

  • Equipment unique to the project
  • Meeting rooms reserved for the project
  • Other project-specific assets

Response: Returns the newly created project resource.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Name of the resource

color
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Color identifier for the resource

Responses

Request samples

Content type
application/json
{
  • "name": "Project Resource",
  • "color": "green1"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "name": "Project Resource",
  • "color": "green1",
  • "created_at": "2024-01-15T10:30:00Z"
}

Get a project resource (legacy route - use resourceId instead)

Retrieves a specific project resource.

Note: This is a legacy route with incorrect path parameter naming. Use GET /projects/{projectId}/resources/project/{resourceId} instead.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "name": "Conference Room A",
  • "color": "blue1",
  • "created_at": "2024-01-15T10:30:00Z"
}

Update a project resource (legacy route)

Updates a project resource.

Note: This is a legacy route with incorrect path parameter naming. Use PATCH /projects/{projectId}/resources/project/{resourceId} instead.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Updated name of the resource

Responses

Request samples

Content type
application/json
{
  • "name": "Updated Resource"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "name": "Conference Room A",
  • "color": "blue1",
  • "created_at": "2024-01-15T10:30:00Z"
}

Delete a project resource (legacy route)

Deletes a project resource.

Note: This is a legacy route with incorrect path parameter naming. Use DELETE /projects/{projectId}/resources/project/{resourceId} instead.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get company resources (labels) for a project

Retrieves all company resources that have been added to this project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Response: Returns an array of company resource objects that are available for task assignments in this project.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add company resource (label) to project

Adds a company resource to a project with a project-specific color.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project and company

Resource Limit: Company must not have reached the maximum resources limit for their plan.

Response: Returns the newly created project-company resource link.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
company_resource_id
required
integer

ID of the company resource to add to the project

color
required
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Color identifier for this resource in the project context

Responses

Request samples

Content type
application/json
{
  • "company_resource_id": 1,
  • "color": "blue2"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "company_resource_id": 2754313,
  • "color": "blue1",
  • "resource": {
    }
}

Update company resource link (legacy route - use company_resource_optionId instead)

Updates a company resource link for a project.

Note: This is a legacy route. Use PATCH /projects/{projectId}/resources/company/{company_resource_optionId} instead.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

companyId
required
integer
Example: 12345

ID of the company resource link (use company_resource_optionId in the newer endpoint)

Request Body schema: application/json
required
company_resource_id
required
integer

ID of the company resource

color
required
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Updated color identifier for this resource

Responses

Request samples

Content type
application/json
{
  • "company_resource_id": 1,
  • "color": "blue2"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "company_resource_id": 2754313,
  • "color": "blue1",
  • "resource": {
    }
}

Remove company resource from project (legacy route)

Removes a company resource from a project.

Note: This is a legacy route. Use DELETE /projects/{projectId}/resources/company/{company_resource_optionId} instead.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

companyId
required
integer
Example: 12345

ID of the company resource link

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

List time blocks for a project

Retrieves all time blocks (time entries) for tasks within a project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Time Blocks: Time blocks represent logged time on tasks, including start time, end time, and the user who logged the time.

Pagination: Use offset and limit query parameters to paginate results.

  • Default limit: 100
  • Maximum limit: 100

Response: Returns a paginated list of time block objects.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

query Parameters
offset
integer >= 0
Default: 0

Pagination offset

limit
integer [ 1 .. 100 ]
Default: 100
Example: limit=100

Maximum number of time blocks to return

page
integer >= 1
Example: page=1

Page number (alternative to offset)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get health reports for projects

Generates health metrics for one or more projects, analyzing task status and completion percentages.

Authentication required: Yes (Bearer token)

Permissions: User must have access to all specified projects

Health Metrics:

  • On Schedule: Tasks progressing as expected
  • Overdue: Tasks past their end date and not 100% complete
  • Behind: Tasks that started but are behind expected progress
  • Upcoming: Tasks not yet started
  • Percent Complete: Overall completion (weighted by task duration)

Calculation: For each project, the endpoint:

  1. Retrieves all tasks
  2. Calculates expected progress based on task duration and current date
  3. Compares actual vs expected progress
  4. Categorizes tasks into health status buckets
  5. Calculates overall project completion percentage

Use Cases:

  • Dashboard health indicators
  • Project status overview
  • Identifying projects needing attention
  • Portfolio health monitoring

Response: Returns an array of health report objects, one for each requested project.

Authorizations:
personalAccessToken
query Parameters
ids[]
Array of integers
Example: ids[]=920883&ids[]=920884

Array of project IDs to generate health reports for

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get project health reports (legacy format)

Generates health metrics for projects in legacy format with project object included.

Note: This is a legacy endpoint. Use GET /reports/health/project for the newer format.

Authentication required: Yes (Bearer token)

Permissions: User must have access to all specified projects

Required: At least one project ID must be provided via ids[] parameter.

Response Format: Returns an array where each entry contains:

  • project: The full project object
  • report_data: Health metrics object

Resource Filtering: The offset parameter can be used to apply resource filters (legacy behavior).

Authorizations:
personalAccessToken
query Parameters
offset
integer >= 0
Example: offset=100

Offset for resource filtering (legacy parameter)

ids[]
required
Array of integers
Example: ids[]=920883

Array of project IDs (required)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List active projects

Retrieves a paginated list of projects accessible to the current user.

Authentication required: Yes (Bearer token)

Default Filters:

  • Status: Active projects only (excludes complete, on hold, and archived)
  • User access: Only projects the user has been invited to or owns

Query Parameters:

  • status: Filter by status (active, on hold, complete, other)
  • offset: Pagination offset (default: 0)
  • limit: Results per page (default: 100)
  • page: Page number (alternative to offset)
  • is_template: Filter templates (true/false)
  • company_ids[]: Filter by specific companies
  • q: Search query to filter by project name

Response: Returns a paginated project list with comprehensive nested data including accesses, teams, metrics, and company information.

Sorting:

  • Starred projects appear first
  • Then sorted alphabetically by name
Authorizations:
personalAccessToken
query Parameters
status
string
Default: "active"
Enum: "active" "on hold" "complete" "other"
Example: status=active

Filter projects by status

offset
integer >= 0
Default: 0

Pagination offset

limit
integer [ 1 .. 100 ]
Default: 100
Example: limit=100

Number of projects per page

page
integer >= 1
Example: page=1

Page number (calculated from offset if not provided)

is_template
boolean

Filter by template status

company_ids[]
Array of integers
Example: company_ids[]=1000

Filter by specific company IDs

q
string
Example: q=website

Search query to filter project names

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a new project

Creates a new project, optionally copying from a template.

Authentication required: Yes (Bearer token)

Permissions: User must be an account holder or advanced user in the company

Company Limits: Company must not have reached the maximum projects limit for their plan.

Creating from Template:

  • Provide template with a template project ID
  • Template project settings will be copied
  • Use import_* flags to control what gets copied (checklists, comments, notes)
  • Global templates automatically import notes and comments

User Invitations:

  • Provide accesses array with user IDs to invite
  • Users are automatically assigned appropriate default permissions

Working Days:

  • chart_days: Array of working days (1=Monday, 7=Sunday)
  • Defaults to Monday-Friday if not specified

Response: Returns the newly created project with all nested data (accesses, teams, metrics, etc.)

Performance: Project creation can take up to 5 minutes for large templates. A timeout is enforced.

Authorizations:
personalAccessToken
Request Body schema: application/json
required
company_id
required
integer

ID of the company to create the project in

name
required
string [ 1 .. 255 ] characters

Name of the project

template
integer

ID of a template project to copy from

start_date
string <date-time>

Project start date (defaults to today if not specified)

chart_days
Array of integers[ items [ 1 .. 7 ] ]

Working days of the week (1=Monday, 7=Sunday). Defaults to [1,2,3,4,5] if not specified.

default_view
string
Default: "gantt"
Enum: "gantt" "list" "board" "calendar" "discussions"

Default view for the project (defaults to 'gantt')

is_template
boolean
Default: false

Whether this project is a template (defaults to false)

has_hours_enabled
boolean
Default: false

Whether hour tracking is enabled (defaults to false)

import_checklists
boolean
Default: false

When copying from a template, whether to import checklist items (defaults to false)

import_comments
boolean
Default: false

When copying from a template, whether to import comments (defaults to false)

import_notes
boolean
Default: false

When copying from a template, whether to import notes (defaults to false)

accesses
Array of integers

Array of user IDs to invite to the project

Responses

Request samples

Content type
application/json
Example
{
  • "company_id": 1000,
  • "name": "Sample Project",
  • "chart_days": [
    ],
  • "default_view": "gantt"
}

Response samples

Content type
application/json
{
  • "id": 920883,
  • "name": "Website Redesign",
  • "company_id": 1000,
  • "status": "active",
  • "default_view": "gantt",
  • "is_template": false,
  • "has_hours_enabled": false,
  • "in_resource_management": true,
  • "allow_scheduling_on_holidays": false,
  • "lock_milestone_dates": false,
  • "calendar_start_date": null,
  • "chart_days": [
    ],
  • "public_key": null,
  • "permission": "admin",
  • "is_starred": false,
  • "created_at": "2024-01-01T00:00:00Z",
  • "accesses": [
    ],
  • "teams": [
    ],
  • "company": { },
  • "integrations": [
    ],
  • "metrics": { }
}

Get all projects (including closed and templates)

Retrieves all projects the user has access to, regardless of status. This includes active, on hold, complete, and template projects.

Authentication required: Yes (Bearer token)

Permissions: User must be authenticated

Filtering: Use query parameters to filter:

  • company_ids[]: Filter by specific companies
  • status: Filter by project status
  • fields[]: Specify which fields to include in the response

Response: Returns a collection of project objects with comprehensive information.

Difference from /projects: The /projects endpoint typically filters to active projects only, while /projects/all returns all accessible projects regardless of status.

Authorizations:
personalAccessToken
query Parameters
company_ids[]
Array of integers
Example: company_ids[]=1000

Filter by specific company IDs

status
string
Enum: "active" "on hold" "complete" "archived"
Example: status=active

Filter by project status

fields[]
Array of strings
Example: fields[]=name&fields[]=status

Specify which fields to include in response

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get project details

Retrieves comprehensive information about a specific project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Response includes:

  • Project metadata (name, status, dates, settings)
  • User accesses with permissions
  • Team assignments
  • Company information with features and plan
  • Integrations
  • Metrics (task counts, progress, etc.)
  • Document metadata
  • Unread comment counts
  • Cost data (if company has cost features enabled)

Use Cases:

  • Loading project details for editing
  • Displaying project overview
  • Checking permissions and features
  • Accessing project configuration
Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
{
  • "id": 920883,
  • "name": "Website Redesign",
  • "company_id": 1000,
  • "status": "active",
  • "default_view": "gantt",
  • "is_template": false,
  • "has_hours_enabled": false,
  • "in_resource_management": true,
  • "allow_scheduling_on_holidays": false,
  • "lock_milestone_dates": false,
  • "calendar_start_date": null,
  • "chart_days": [
    ],
  • "public_key": null,
  • "permission": "admin",
  • "is_starred": false,
  • "created_at": "2024-01-01T00:00:00Z",
  • "accesses": [
    ],
  • "teams": [
    ],
  • "company": { },
  • "integrations": [
    ],
  • "metrics": { }
}

Update project settings

Updates project settings and configuration. Supports partial updates.

Authentication required: Yes (Bearer token)

Permissions:

  • Admin permissions required for most fields
  • Access permissions sufficient for updating is_starred only

Updateable Fields:

  • name: Project name
  • status: Project status (active, on hold, complete)
  • default_view: Default view mode
  • chart_days: Working days of the week
  • is_template: Template status
  • has_hours_enabled: Hour tracking
  • in_resource_management: Resource management visibility
  • allow_scheduling_on_holidays: Holiday scheduling
  • lock_milestone_dates: Milestone date locking
  • calendar_start_date: Calendar start date override
  • public_key: Public access key
  • is_starred: Starred status (only requires access permission)

Status Changes:

  • Changing from "complete" to "active" or "on hold" requires permission to add projects (counts against plan limits)

History: All changes are logged to the project history.

Response: Returns the updated project object with all nested relationships.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
name
string [ 1 .. 255 ] characters

Updated project name

status
string
Enum: "active" "on hold" "complete"

Updated project status

default_view
string
Enum: "gantt" "list" "board" "calendar" "discussions"

Updated default view

is_template
boolean

Updated template status

has_hours_enabled
boolean

Updated hour tracking setting

in_resource_management
boolean

Updated resource management visibility

allow_scheduling_on_holidays
boolean

Updated holiday scheduling setting

lock_milestone_dates
boolean

Updated milestone date locking setting

calendar_start_date
string or null <date>

Updated calendar start date

chart_days
Array of integers[ items [ 1 .. 7 ] ]

Updated working days

public_key
string or null

Updated public key

is_starred
boolean

Updated starred status for current user

Responses

Request samples

Content type
application/json
Example
{
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "id": 920883,
  • "name": "Website Redesign",
  • "company_id": 1000,
  • "status": "active",
  • "default_view": "gantt",
  • "is_template": false,
  • "has_hours_enabled": false,
  • "in_resource_management": true,
  • "allow_scheduling_on_holidays": false,
  • "lock_milestone_dates": false,
  • "calendar_start_date": null,
  • "chart_days": [
    ],
  • "public_key": null,
  • "permission": "admin",
  • "is_starred": false,
  • "created_at": "2024-01-01T00:00:00Z",
  • "accesses": [
    ],
  • "teams": [
    ],
  • "company": { },
  • "integrations": [
    ],
  • "metrics": { }
}

Archive a project

Archives a project, effectively soft-deleting it. Archived projects do not appear in normal project lists.

Authentication required: Yes (Bearer token)

Permissions: User must have admin permissions on the project

Effects:

  • Project status is changed to "Archived"
  • Project no longer appears in active project lists
  • All tasks, groups, and data remain intact
  • Project can be restored by changing status back to "active"

History: The status change is logged to the project history.

Response: Returns 204 No Content on success.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Export projects to CSV

Exports one or more projects to CSV format, generating a downloadable file with project and task data.

Authentication required: Yes (Bearer token)

Permissions: User must have access to all specified projects

Export Contents:

  • Project information
  • All groups and tasks
  • Task dates, progress, assignments
  • Resources
  • Dependencies

Multiple Projects: Can export multiple projects in a single CSV file by providing multiple IDs.

Timeout: A 2-minute timeout is enforced due to potentially large data export.

Response: Returns a document object with a URL to download the generated CSV file.

Authorizations:
personalAccessToken
query Parameters
ids[]
required
Array of integers
Example: ids[]=920883

Array of project IDs to export

Responses

Response samples

Content type
application/json
{}

Get project children (groups and tasks)

Retrieves all groups and tasks for a project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Nested vs Flat:

  • Default: Returns groups with nested children (groups contain tasks and subgroups)
  • With is_flat_list=true: Returns a flat list of all groups and tasks

Response: Returns an array of groups and tasks. By default, the structure is hierarchical with root groups containing their children.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

query Parameters
is_flat_list
boolean
Example: is_flat_list=true

Return children as a flat list instead of nested structure

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Bulk update all tasks in a project

Updates all tasks in a project with the same values. This is useful for bulk operations like changing the color of all tasks.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Transaction Safety: All task updates are performed within a transaction. If any update fails, the entire operation is rolled back.

Updateable Fields: Any field that can be updated on a single task can be bulk updated:

  • color: Change color for all tasks
  • Other task update fields (see UpdateTaskRequest schema)

Task Filters: The bulk update applies to all tasks matching the standard task query filters for the project.

Response: Returns an array of all updated task objects.

Performance: This operation can be slow for projects with many tasks. A 5-minute timeout is enforced.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
color
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Update the color for all tasks in the project

Responses

Request samples

Content type
application/json
{
  • "color": "blue1"
}

Response samples

Content type
application/json
[
  • {
    }
]

Accept pending project invitations

Accepts all pending project invitations for the current user.

Authentication required: Yes (Bearer token)

Permissions: User must be authenticated

Behavior: Accepts all pending project invitations that the current user has received. This is useful for bulk accepting invitations.

Response: Returns 204 No Content on success.

Authorizations:
personalAccessToken

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Move project children

Moves tasks, groups, or projects to a new location within the project hierarchy.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the target location

Move Intent:

  • above: Place children above the target
  • below: Place children below the target
  • within: Place children as children of the target

Target Types: Can be a task, group, or project

Response: Returns the updated project structure.

Authorizations:
personalAccessToken
Request Body schema: application/json
required
required
Array of objects

Array of child items to move

Array
type
required
string
Enum: "task" "group" "project"

Type of the child item

id
required
integer

ID of the child item

required
object
type
required
string
Enum: "task" "group" "project"

Type of the target location

id
required
integer

ID of the target location

intent
required
string
Enum: "above" "below" "within"

Where to place the children relative to the target

Responses

Request samples

Content type
application/json
{
  • "children": [
    ],
  • "target": {
    },
  • "intent": "within"
}

Response samples

Content type
application/json
{ }

Get company resources (labels) available for a project

Retrieves all company-level resources that can be assigned to tasks in this project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Company Resources: These are resources defined at the company level (equipment, meeting rooms, etc.) that can be shared across multiple projects within the company.

Response: Returns an array of company resource objects. These resources can be added to the project using POST /projects/{projectId}/resources/company.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add company resource (label) to project

Adds a company resource to a project, making it available for task assignments.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project and company

Company Resource: The resource must already exist at the company level and belong to the same company as the project.

Color: Each project can assign a custom color to a company resource, overriding the company-level color for this specific project context.

Response: Returns the newly created project-company resource link with the assigned color.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
company_resource_id
required
integer

ID of the company resource to add to the project

color
required
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Color identifier for this resource in the project context

Responses

Request samples

Content type
application/json
{
  • "company_resource_id": 2754313,
  • "color": "blue2"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "company_resource_id": 2754313,
  • "color": "blue2",
  • "resource": {
    }
}

List project-specific resources (labels) (alias)

Retrieves all project-specific resources. This is an alias for /projects/{projectId}/resources/project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Note: Use /projects/{projectId}/resources/project instead for consistency.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a project-specific resource (alias)

Creates a new project-specific resource. This is an alias for POST /projects/{projectId}/resources/project.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project and company

Note: Use /projects/{projectId}/resources/project instead for consistency.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Name of the resource

color
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Color identifier for the resource

Responses

Request samples

Content type
application/json
{
  • "name": "Rick Resource",
  • "color": "blue1"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "name": "Conference Room A",
  • "color": "blue1",
  • "created_at": "2024-01-15T10:30:00Z"
}

Get a project resource (label)

Retrieves a specific project resource by ID.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Project Resources: These are resources specific to the project (not company-wide).

Response: Returns the project resource object with name and color.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

resourceId
required
integer >= 1
Example: 1000

Unique identifier of the resource assigned to a task

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "name": "Conference Room A",
  • "color": "blue2",
  • "created_at": "2024-01-15T10:30:00Z"
}

Update a project resource (label)

Updates a project resource's properties (name and/or color).

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Updateable Fields:

  • name: Resource name (required in request)

Response: Returns the updated project resource object.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

resourceId
required
integer >= 1
Example: 1000

Unique identifier of the resource assigned to a task

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Updated name of the resource

Responses

Request samples

Content type
application/json
{
  • "name": "Test POST Project Resource Name Update"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "name": "Test POST Project Resource Name Update",
  • "color": "blue2",
  • "created_at": "2024-01-15T10:30:00Z"
}

Get critical path for a project

Calculates and returns the critical path for a project - the sequence of tasks that determines the minimum project duration.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Critical Path: The critical path is the longest sequence of dependent tasks that must be completed on time for the project to finish by its due date. Tasks on the critical path have zero slack time - any delay will delay the entire project.

Calculation:

  • Analyzes all task dependencies
  • Accounts for holidays and non-working days
  • Calculates slack time for each task
  • Identifies tasks with zero slack (critical tasks)
  • Returns predecessor and successor IDs for each critical task

Empty Response: If the project has no tasks, returns an empty array.

Use Cases:

  • Identify tasks that require close monitoring
  • Determine which tasks can be delayed without affecting project completion
  • Optimize resource allocation to critical tasks
  • Visualize project bottlenecks
Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

reports

Report endpoints

Get health reports for boards

Generates health metrics for one or more boards, analyzing task status and completion percentages.

Authentication required: Yes (Bearer token)

Permissions: User must have access to all specified boards

Health Metrics:

  • On Schedule: Tasks progressing as expected
  • Overdue: Tasks past their end date and not 100% complete
  • Behind: Tasks that started but are behind expected progress
  • Upcoming: Tasks not yet started
  • Percent Complete: Overall completion (weighted by task duration)

Calculation: For each board, the endpoint:

  1. Retrieves all cards and their associated tasks
  2. Analyzes each task's dates and progress
  3. Compares actual vs expected progress based on current date
  4. Categorizes tasks into health status buckets

Response: Returns an array of health report objects, one for each requested board.

Authorizations:
personalAccessToken
query Parameters
ids[]
Array of strings <uuid> [ items <uuid > ]
Example: ids[]=443c80e4-72dc-4363-afd8-b58e6d866b63

Array of board IDs (UUIDs) to generate health reports for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get health reports for projects

Generates health metrics for one or more projects, analyzing task status and completion percentages.

Authentication required: Yes (Bearer token)

Permissions: User must have access to all specified projects

Health Metrics:

  • On Schedule: Tasks progressing as expected
  • Overdue: Tasks past their end date and not 100% complete
  • Behind: Tasks that started but are behind expected progress
  • Upcoming: Tasks not yet started
  • Percent Complete: Overall completion (weighted by task duration)

Calculation: For each project, the endpoint:

  1. Retrieves all tasks
  2. Calculates expected progress based on task duration and current date
  3. Compares actual vs expected progress
  4. Categorizes tasks into health status buckets
  5. Calculates overall project completion percentage

Use Cases:

  • Dashboard health indicators
  • Project status overview
  • Identifying projects needing attention
  • Portfolio health monitoring

Response: Returns an array of health report objects, one for each requested project.

Authorizations:
personalAccessToken
query Parameters
ids[]
Array of integers
Example: ids[]=920883&ids[]=920884

Array of project IDs to generate health reports for

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get project health reports (legacy format)

Generates health metrics for projects in legacy format with project object included.

Note: This is a legacy endpoint. Use GET /reports/health/project for the newer format.

Authentication required: Yes (Bearer token)

Permissions: User must have access to all specified projects

Required: At least one project ID must be provided via ids[] parameter.

Response Format: Returns an array where each entry contains:

  • project: The full project object
  • report_data: Health metrics object

Resource Filtering: The offset parameter can be used to apply resource filters (legacy behavior).

Authorizations:
personalAccessToken
query Parameters
offset
integer >= 0
Example: offset=100

Offset for resource filtering (legacy parameter)

ids[]
required
Array of integers
Example: ids[]=920883

Array of project IDs (required)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get time tracking report (Beta)

Generates a time tracking report for the specified date range.

Status: This endpoint is in beta and may change.

Authentication required: Yes (Bearer token)

Permissions: User must be authenticated

Date Range: Use start_date and end_date to specify the reporting period. If not provided, defaults may apply based on implementation.

Response: Returns time tracking data aggregated by the specified parameters.

Note: This is a beta endpoint. The response format and parameters may change in future versions.

Authorizations:
personalAccessToken
query Parameters
start_date
string <date>
Example: start_date=2020-01-01

Start date for the report (YYYY-MM-DD format)

end_date
string <date>
Example: end_date=2020-12-31

End date for the report (YYYY-MM-DD format)

Responses

Response samples

Content type
application/json
{ }

schedule-confirmations

Schedule confirmation endpoints

Send schedule confirmation notifications

Sends schedule confirmation notifications to users for specific tasks.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the tasks

Behavior:

  • Finds existing schedule confirmations for the specified user-task combinations
  • Sends notification emails to users
  • Updates confirmation status to "Pending"
  • Only processes confirmations with status "NotNotified" or "Pending"

Response: Returns 204 No Content on success.

Authorizations:
personalAccessToken
Request Body schema: application/json
required
required
Array of objects

Array of user-task combinations to send confirmations for

Array
user_id
required
integer

ID of the user to notify

task_ids
required
Array of integers

Array of task IDs to include in the confirmation

Responses

Request samples

Content type
application/json
{
  • "user_tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Update schedule confirmation status

Updates the status of a schedule confirmation.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the company

Updateable Fields:

  • status: New status for the confirmation (must be a valid ScheduleConfirmationStatus value)

Response: Returns the updated schedule confirmation.

Authorizations:
personalAccessToken
path Parameters
scheduleConfirmationId
required
integer >= 1
Example: 12345

Unique identifier of the schedule confirmation

Request Body schema: application/json
required
status
required
string
Enum: "not_notified" "pending" "confirmed" "declined"

New status for the confirmation

Responses

Request samples

Content type
application/json
{
  • "status": "confirmed"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "resource_link_id": 67890,
  • "sender_id": 123,
  • "original_start_date": "2024-01-15T09:00:00Z",
  • "original_end_date": "2024-01-20T17:00:00Z",
  • "new_start_date": "2024-01-16T09:00:00Z",
  • "new_end_date": "2024-01-21T17:00:00Z",
  • "status": "pending",
  • "task_name": "Design Review",
  • "project_name": "Website Redesign",
  • "company_id": 123456
}

tasks

Task management endpoints

Get discussions for a task

Retrieves discussion metadata for a task, including comment counts and read status.

This endpoint provides a summary view of the task's discussion activity without returning the full comment content. It's useful for showing discussion indicators in list views or determining which tasks have unread comments.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the task

Response includes:

  • Total comment count
  • Unread comment count for current user
  • Last comment timestamp
  • Starred/mentioned status

Use cases:

  • Show unread comment badges in task lists
  • Display discussion activity indicators
  • Filter tasks by discussion activity
  • Identify tasks needing attention

Note: To get actual comment content, use the comments endpoint: GET /v1/tasks/{taskId}/comments

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get cards for a task

Retrieves all board cards associated with a specific task.

Board cards represent the task's presence on one or more kanban-style boards. A single task can appear on multiple boards in different columns.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the task and the boards

Query Optimization: Use the include parameter to load related data (board, board.columns, board.columns.cards) in a single request to reduce the number of API calls needed.

Use cases:

  • See which boards this task appears on
  • Track task status across multiple boards
  • Manage board-based workflows
Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

query Parameters
include
string
Example: include=board,board.columns

Comma-separated list of relationships to include in the response

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ]
}

List task documents

Retrieves all documents attached to a specific task.

Documents include files uploaded directly to the task such as specifications, images, PDFs, and other file types. Each document may have multiple versions.

Authentication required: Yes (Bearer token)

Permissions: User must have read access to the task

Response includes:

  • Document metadata (name, size, type)
  • All versions of each document
  • Upload information (who uploaded, when)
  • Download URLs
Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

Responses

Response samples

Content type
application/json
{}

Upload a document to a task

Uploads a new document file to a task or adds a new version to an existing document.

This endpoint accepts multipart/form-data file uploads. The uploaded file is stored securely and associated with the task.

Authentication required: Yes (Bearer token)

Permissions: User must have upload permissions on the task

Supported file types: Most common file types are supported (PDF, images, Office docs, etc.)

File size limits: Check with your organization's limits

Note: Use multipart/form-data for file uploads, not application/json

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

query Parameters
parent
integer
Example: parent=67890

ID of parent document (for adding a new version to existing document)

Request Body schema: multipart/form-data
required

Document file to upload

file
required
string <binary>

The file to upload

description
string

Optional description of the document

Responses

Response samples

Content type
application/json
{}

Mark all task documents as read

Marks all documents attached to a task as read for the current user.

This endpoint is used to clear unread indicators on documents, similar to marking emails as read. It affects only the current user's read status.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the task

Use cases:

  • Clear all unread document notifications for a task
  • Batch mark documents as reviewed
  • Update user's document read tracking
Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

Responses

Response samples

Content type
application/json
{
  • "message": "All documents marked as read"
}

Update a document

Updates metadata for a specific document attached to a task.

This endpoint allows updating document properties such as name and description. The file content itself cannot be changed - to update the file, upload a new version instead.

Authentication required: Yes (Bearer token)

Permissions: User must have edit access to the task

Note: To update the actual file content, upload a new version using the POST /v1/tasks/{taskId}/documents endpoint with the parent parameter.

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

documentId
required
integer >= 1
Example: 67890

Unique identifier of the document

Request Body schema: application/json
required

Updated document metadata

name
string [ 1 .. 255 ] characters

Updated name for the document

description
string <= 1000 characters

Updated description

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Final Project Specifications v2"
}

Response samples

Content type
application/json
{}

Delete a document

Permanently deletes a document and all its versions from a task.

Warning: This action cannot be undone. All versions of the document will be permanently deleted from storage.

Authentication required: Yes (Bearer token)

Permissions: User must have edit access to the task

Impact:

  • Document file is permanently deleted
  • All versions are removed
  • Document is removed from any comments referencing it
  • This action is logged in task history
Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

documentId
required
integer >= 1
Example: 67890

Unique identifier of the document

Responses

Response samples

Content type
application/json
{
  • "message": "Document deleted successfully",
  • "data": {
    }
}

Get task history

Retrieves the complete audit log of all changes made to a task.

History entries track every modification including:

  • Name changes
  • Date changes
  • Completion percentage updates
  • Color changes
  • Estimated hours modifications
  • Resource assignments
  • Comments added/edited/deleted
  • And more...

Each history entry includes what was changed, the new value, who made the change, and when it occurred.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the task

Pagination: Results are paginated using offset/limit parameters. Default limit is 50 entries.

Use cases:

  • Audit trail for compliance
  • Track task evolution over time
  • See who made specific changes
  • Understand task timeline
Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

query Parameters
offset
integer >= 0
Default: 0

Offset for pagination of history entries

limit
integer [ 1 .. 100 ]
Default: 50
Example: limit=50

Maximum number of history entries to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Bulk update all tasks in a project

Updates all tasks in a project with the same values. This is useful for bulk operations like changing the color of all tasks.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Transaction Safety: All task updates are performed within a transaction. If any update fails, the entire operation is rolled back.

Updateable Fields: Any field that can be updated on a single task can be bulk updated:

  • color: Change color for all tasks
  • Other task update fields (see UpdateTaskRequest schema)

Task Filters: The bulk update applies to all tasks matching the standard task query filters for the project.

Response: Returns an array of all updated task objects.

Performance: This operation can be slow for projects with many tasks. A 5-minute timeout is enforced.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
color
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Update the color for all tasks in the project

Responses

Request samples

Content type
application/json
{
  • "color": "blue1"
}

Response samples

Content type
application/json
[
  • {
    }
]

List checklist items for a task

Retrieves all checklist items associated with a specific task.

Checklist items are ordered by their sort property in ascending order. They represent subtasks or action items that need to be completed as part of the main task.

Authentication required: Yes (Bearer token)

Permissions: User must have read access to the task

Use cases:

  • View task breakdown into actionable items
  • Track completion of individual task components
  • Manage task sub-requirements
Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a checklist item

Creates a new checklist item for a task.

Checklist items help break down tasks into smaller, trackable action items. The sort order determines the display order in the checklist.

Authentication required: Yes (Bearer token)

Permissions: User must have editProgress permission on the task

Note: The is_complete and sort fields are optional. If not provided, is_complete defaults to false and sort is auto-assigned.

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

Request Body schema: application/json
required

Checklist item data

name
required
string [ 1 .. 255 ] characters

Name/description of the checklist item

is_complete
boolean
Default: false

Initial completion status

sort
integer

Sort order within the checklist

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Review design mockups"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a checklist item

Updates one or more properties of an existing checklist item.

This endpoint supports partial updates - only include the fields you want to change. Common updates include marking items complete, renaming them, or reordering.

Authentication required: Yes (Bearer token)

Permissions: User must have editProgress permission on the task

Use cases:

  • Mark items as complete/incomplete
  • Update item descriptions
  • Reorder checklist items
Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

checklist_itemId
required
integer >= 1
Example: 54321

Unique identifier of the checklist item

Request Body schema: application/json
required

Fields to update (partial update supported)

name
string [ 1 .. 255 ] characters

Updated name/description

is_complete
boolean

Updated completion status

sort
integer

Updated sort order

Responses

Request samples

Content type
application/json
Example
{
  • "is_complete": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a checklist item

Permanently deletes a checklist item from a task.

Authentication required: Yes (Bearer token)

Permissions: User must have editProgress permission on the task

Warning: This action cannot be undone.

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

checklist_itemId
required
integer >= 1
Example: 54321

Unique identifier of the checklist item

Responses

Response samples

Content type
application/json
{
  • "message": "Checklist item deleted successfully"
}

Get resources assigned to a task

Retrieves all resources (users or labels) assigned to a specific task.

Each resource assignment includes allocation details such as hours per day, total hours, and the resource's profile information.

Authentication required: Yes (Bearer token)

Permissions: User must have read access to the project containing the task

Use cases:

  • See who is assigned to work on a task
  • Check resource allocation and capacity
  • Verify team member assignments
Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

query Parameters
type
string
Enum: "user" "team" "company_resource"
Example: type=user

Filter resources by type

Responses

Response samples

Content type
application/json
{
  • "data": []
}

Assign a resource to a task

Assigns a new resource (users or labels) to a task.

When assigning a resource, you specify the allocation in terms of hours per day and total hours. This affects capacity planning and workload calculations.

Authentication required: Yes (Bearer token)

Permissions: User must have write access to the project

Note: The same resource can only be assigned to a task once. To modify an existing assignment, use the PATCH endpoint for the specific resource.

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

Request Body schema: application/json
required

Resource assignment data

type
required
string
Enum: "user" "company" "project"

Type of resource being assigned

type_id
required
integer

ID of the user, company resource, or project resource

hours_per_day
number or null [ 0 .. 24 ]

Hours per day to allocate this resource (nullable)

total_hours
number or null >= 0

Total hours to allocate for this resource (nullable)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "user",
  • "type_id": 1000,
  • "hours_per_day": 8,
  • "total_hours": 40
}

Response samples

Content type
application/json
{
  • "data": {},
  • "message": "Resource assigned successfully"
}

Update a resource assignment

Updates an existing resource assignment on a task.

You can modify the allocation hours for the resource. This endpoint supports partial updates - only include the fields you want to change.

Authentication required: Yes (Bearer token)

Permissions: User must have write access to the project

Note: Only hours_per_day and total_hours can be updated via this endpoint. To change the resource itself, you must delete and re-add.

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

resourceId
required
integer >= 1
Example: 1000

Unique identifier of the resource assigned to a task

Request Body schema: application/json
optional

Resource allocation data to update (partial update supported)

hours_per_day
number or null [ 0 .. 24 ]

Updated hours per day allocation (nullable)

total_hours
number or null >= 0

Updated total hours allocation (nullable)

Responses

Request samples

Content type
application/json
Example
{
  • "hours_per_day": 5,
  • "total_hours": 25
}

Response samples

Content type
application/json
{
  • "data": {},
  • "message": "Resource assignment updated successfully"
}

Remove a resource from a task

Removes a resource assignment from a task.

This unassigns the user, team, or company resource from the task, removing their allocation and any associated time blocks.

Authentication required: Yes (Bearer token)

Permissions: User must have write access to the project

Warning: This action will delete associated time blocks and may affect capacity planning calculations. It cannot be undone.

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

resourceId
required
integer >= 1
Example: 1000

Unique identifier of the resource assigned to a task

Responses

Response samples

Content type
application/json
{
  • "message": "Resource removed from task successfully",
  • "data": {
    }
}

Create a task dependency

Creates a dependency relationship between two tasks.

Task dependencies define the order in which tasks must be completed. The dependency relationship is directional: the current task (from_task) depends on the specified task (to_task).

Authentication required: Yes (Bearer token)

Permissions: User must have edit access to both tasks' projects

Dependency Types:

  • FS (Finish-to-Start) - Most common. Task cannot start until predecessor finishes.
  • SS (Start-to-Start) - Task cannot start until predecessor starts. Requires Advanced Dependencies feature.
  • FF (Finish-to-Finish) - Task cannot finish until predecessor finishes. Requires Advanced Dependencies feature.
  • SF (Start-to-Finish) - Task cannot finish until predecessor starts. Requires Advanced Dependencies feature.

Lead/Lag Time:

  • Positive values add lag time (delay) after the predecessor
  • Negative values add lead time (overlap with predecessor)
  • Measured in days

Validation:

  • Cannot create self-referencing dependencies
  • Cannot create duplicate dependencies
  • Advanced dependency types (SS, FF, SF) require company feature flag
Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

Request Body schema: application/json
required

Dependency relationship data

required
object

The task to create a dependency to (the predecessor)

id
required
integer

ID of the predecessor task

lead_lag_time
integer or null
Default: 0

Lead or lag time in days (positive for lag, negative for lead)

type
string
Default: "FS"
Enum: "FS" "SS" "FF" "SF"

Type of dependency - FS (Finish-to-Start), SS (Start-to-Start), FF (Finish-to-Finish), SF (Start-to-Finish)

Responses

Request samples

Content type
application/json
Example
{
  • "to_task": {
    },
  • "type": "FS",
  • "lead_lag_time": 0
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "Dependency created successfully"
}

Delete a task dependency

Removes a dependency relationship between two tasks.

Deleting a dependency removes the scheduling constraint between tasks. This allows tasks to be scheduled independently again.

Authentication required: Yes (Bearer token)

Permissions: User must have edit access to the project

Impact:

  • Dependency relationship is permanently removed
  • Task scheduling becomes independent
  • May affect critical path calculations
  • Action is logged in project history
  • May impact dependent task dates if auto-scheduling is enabled

Note: This does not delete the tasks themselves, only the dependency between them.

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

dependencieId
required
integer >= 1
Example: 12345

Unique identifier of the dependency to delete

Responses

Response samples

Content type
application/json
{
  • "message": "Dependency deleted successfully",
  • "data": {
    }
}

Get tasks for the current user

Retrieves a list of tasks assigned to or visible by the authenticated user.

This endpoint supports filtering by project IDs, date ranges, and specific user resources. Tasks are returned with their basic information including dates, progress, and assignments.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the projects containing the tasks

Use cases:

  • Get all tasks for a specific project
  • Filter tasks by date range to see what's coming up
  • View tasks assigned to specific team members
Authorizations:
personalAccessToken
query Parameters
project_ids[]
Array of integers
Example: project_ids[]=920883&project_ids[]=920884

Array of project IDs to filter tasks. Can be specified multiple times for multiple projects.

start_date
string <date>
Example: start_date=2017-10-04

Filter tasks starting on or after this date (ISO 8601 format YYYY-MM-DD)

end_date
string <date>
Example: end_date=2017-10-11

Filter tasks ending on or before this date (ISO 8601 format YYYY-MM-DD)

user_resource_ids
string^[0-9]+(,[0-9]+)*$
Example: user_resource_ids=1000,1001

Comma-separated list of user resource IDs to filter tasks assigned to specific users

include_completed
boolean
Default: false
Example: include_completed=true

Include completed tasks in the results

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

per_page
integer [ 1 .. 100 ]
Default: 50
Example: per_page=50

Number of tasks per page

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a new task

Creates a new task within a specified project and parent group.

The task will be created with the provided name and must belong to both a project and a parent group. Additional properties like dates, duration, and completion percentage are optional.

Authentication required: Yes (Bearer token)

Permissions: User must have write access to the project

Authorizations:
personalAccessToken
Request Body schema: application/json
required

Task data to create

project_id
required
integer

ID of the project where the task will be created

parent_group_id
required
integer

ID of the parent group that will contain this task

name
required
string [ 1 .. 255 ] characters

Name/title of the task

start_date
string <date>

Start date of the task (YYYY-MM-DD)

end_date
string <date>

End date of the task (YYYY-MM-DD)

duration
integer >= 1

Duration of the task in days (calculated from start_date and end_date)

percent_complete
integer [ 0 .. 100 ]
Default: 0

Initial completion percentage

color
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Color identifier for the task in the UI. Falls back to user's default color if not specified.

type
string
Enum: "task" "milestone"

Type of task - regular task or milestone. Milestones must have matching start_date and end_date.

estimated_hours
number >= 0

Estimated hours to complete the task

estimate
string

Estimate/sizing label (e.g., "S", "M", "L", or custom values)

sort
integer

Sort order within the parent group

is_starred
boolean
Default: false

Whether the task should be starred for the current user

object (TaskCost)

Cost information associated with a task

cost
required
integer >= 0

Total cost in cents (e.g., 50000 = $500.00)

cost_load_mode
required
string
Enum: "front" "back" "even"

How the cost is distributed across the task duration

Responses

Request samples

Content type
application/json
Example
{
  • "project_id": 920883,
  • "parent_group_id": 456789,
  • "name": "New task created via API"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "Task created successfully"
}

Create multiple tasks in bulk

Creates multiple tasks at once within a specified project.

This endpoint allows you to create up to 100 tasks in a single API call, which is more efficient than creating tasks one by one. All tasks must belong to the same project but can have different parent groups.

Authentication required: Yes (Bearer token)

Permissions: User must have write access to the project

Rate limiting: This endpoint may have stricter rate limits due to the bulk nature

Use cases:

  • Import tasks from external systems
  • Create template-based task sets
  • Quickly scaffold a new project phase
Authorizations:
personalAccessToken
Request Body schema: application/json
required

Bulk task creation data

project_id
required
integer

ID of the project where tasks will be created

required
Array of objects (CreateTaskRequest) [ 1 .. 100 ] items

Array of task objects to create

Array ([ 1 .. 100 ] items)
project_id
required
integer

ID of the project where the task will be created

parent_group_id
required
integer

ID of the parent group that will contain this task

name
required
string [ 1 .. 255 ] characters

Name/title of the task

start_date
string <date>

Start date of the task (YYYY-MM-DD)

end_date
string <date>

End date of the task (YYYY-MM-DD)

duration
integer >= 1

Duration of the task in days (calculated from start_date and end_date)

percent_complete
integer [ 0 .. 100 ]
Default: 0

Initial completion percentage

color
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Color identifier for the task in the UI. Falls back to user's default color if not specified.

type
string
Enum: "task" "milestone"

Type of task - regular task or milestone. Milestones must have matching start_date and end_date.

estimated_hours
number >= 0

Estimated hours to complete the task

estimate
string

Estimate/sizing label (e.g., "S", "M", "L", or custom values)

sort
integer

Sort order within the parent group

is_starred
boolean
Default: false

Whether the task should be starred for the current user

object (TaskCost)

Cost information associated with a task

Responses

Request samples

Content type
application/json
Example
{
  • "project_id": 920883,
  • "tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "message": "3 tasks created successfully",
  • "meta": {
    }
}

Get a specific task

Retrieves detailed information about a single task by its ID.

This endpoint returns all task properties including name, dates, progress, cost information, and metadata.

Authentication required: Yes (Bearer token)

Permissions: User must have read access to the project containing the task

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a task

Updates one or more properties of an existing task.

This endpoint supports partial updates - you only need to send the fields you want to change. Common updates include changing dates, updating progress, or modifying cost information.

Authentication required: Yes (Bearer token)

Permissions: User must have write access to the project containing the task

Note: Some fields like id, project_id, and created_at cannot be updated

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

Request Body schema: application/json
required

Fields to update (partial update supported)

name
string [ 1 .. 255 ] characters

Updated name/title of the task

start_date
string <date>

Updated start date (YYYY-MM-DD)

end_date
string <date>

Updated end date (YYYY-MM-DD)

percent_complete
integer [ 0 .. 100 ]

Updated completion percentage

color
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Updated color identifier for the task

type
string
Enum: "task" "milestone"

Updated task type

estimated_hours
number >= 0

Updated estimated hours

estimate
string

Updated estimate/sizing label

is_starred
boolean

Updated starred status for the current user

parent_group_id
integer

Move task to a different parent group (reparenting)

object (TaskCost)

Cost information associated with a task

cost
required
integer >= 0

Total cost in cents (e.g., 50000 = $500.00)

cost_load_mode
required
string
Enum: "front" "back" "even"

How the cost is distributed across the task duration

Responses

Request samples

Content type
application/json
Example
{
  • "task_cost": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "Task updated successfully"
}

Delete a task

Permanently deletes a task from a project.

Warning: This action cannot be undone. All associated data including comments, time tracking, and resource assignments will also be deleted.

Authentication required: Yes (Bearer token)

Permissions: User must have delete permissions on the project

Best practice: Consider archiving or marking tasks as complete instead of deleting them to preserve project history.

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

Responses

Response samples

Content type
application/json
{
  • "message": "Task deleted successfully",
  • "data": {
    }
}

Convert a task to a subgroup

Converts an existing task into a subgroup (folder) that can contain other tasks.

This operation transforms a task into a group, allowing you to reorganize your project structure by nesting tasks under what was previously a single task.

Authentication required: Yes (Bearer token)

Permissions: User must have edit access to the task

What happens:

  • Task is converted to a group with the same name
  • Task properties are preserved where applicable
  • The new group is placed in the same position as the original task
  • Can optionally flatten nested children for a flat list view

Use cases:

  • Reorganizing project structure
  • Creating hierarchical task breakdown
  • Converting deliverable into a phase with subtasks

Note: This operation cannot be reversed automatically. The task ID becomes a group ID after conversion.

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

query Parameters
flatten_children
boolean
Example: flatten_children=true

Whether to flatten nested groups into a flat list structure

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get time blocks for a task

Retrieves all time blocks (scheduled work periods) associated with a specific task.

Time blocks represent planned work periods for the task, showing when resources have worked on it. Each time block includes start/end dates, allocated hours, and the assigned resource.

Authentication required: Yes (Bearer token)

Permissions: User must have read access to the project containing the task

Use cases:

  • View the task's work history
  • Check resource allocation over time
  • Understand task timeline and capacity planning
Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

query Parameters
start_date
string <date>
Example: start_date=2024-01-15

Filter time blocks starting on or after this date (YYYY-MM-DD)

end_date
string <date>
Example: end_date=2024-01-31

Filter time blocks ending on or before this date (YYYY-MM-DD)

resource_id
integer
Example: resource_id=1000

Filter time blocks by specific resource ID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Duplicate a task

Creates a copy of an existing task with all its properties and attributes.

The duplicated task will be created in the same parent group as the original, with all task properties copied including name, dates, resources, and dependencies where applicable.

Authentication required: Yes (Bearer token)

Permissions: User must have edit access to the task's project

What gets duplicated:

  • Task properties (name, dates, completion %, color, etc.)
  • Assigned resources
  • Checklist items
  • Custom fields

What does NOT get duplicated:

  • Comments
  • Documents
  • Time tracking entries
  • Task history
Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "Task duplicated successfully"
}

Request progress update for task

Sends a request for a progress update on a task.

Authentication required: Yes (Bearer token)

Permissions: User must be a project admin

Behavior: Queues a progress request notification for the task. This is typically used to prompt task assignees to update their progress.

Response: Returns 204 No Content on success.

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Add a material to a task

Creates a new material item associated with a task. Materials represent physical items or supplies needed for task completion (e.g., equipment, materials, supplies).

Materials track lead times to help with project planning and include a purchaser assignment to manage procurement responsibilities.

Authentication required: Yes (Bearer token)

Permissions: User must have edit access to the task's project

Validation: At least one of months, weeks, or days in lead_time must be greater than 0. The purchaser_id, if provided, must be an active user on the project.

Authorizations:
personalAccessToken
path Parameters
taskId
required
integer >= 1
Example: 12345

Unique identifier of the task

Request Body schema: application/json
required

Material data to create

name
required
string [ 1 .. 255 ] characters

Name/description of the material

required
object

Lead time breakdown for the material

months
required
integer >= 0

Number of months lead time

weeks
required
integer >= 0

Number of weeks lead time

days
required
integer >= 0

Number of days lead time

purchaser_id
integer or null

ID of the user responsible for purchasing (must be on the project)

status
string
Default: "not_ordered"
Enum: "not_ordered" "ordered" "delayed" "delivered"

Initial status of the material

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Windows",
  • "lead_time": {
    },
  • "purchaser_id": 1000,
  • "status": "not_ordered"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

templates

Template management endpoints

List all global templates

Retrieves all global project templates available for creating new projects.

Authentication required: Yes (Bearer token)

Templates: Global templates are pre-configured project structures created by TeamGantt or your company admins. They provide starting points for common project types.

Use Cases:

  • Displaying template options when creating a project
  • Browsing available templates
  • Getting template IDs for project creation

Response: Returns an array of template objects sorted by their sort order.

Note: To get templates organized by category, use GET /templates/groups instead.

Authorizations:
personalAccessToken

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get templates organized by groups

Retrieves all global templates organized by template groups/categories.

Authentication required: Yes (Bearer token)

Template Groups: Templates are organized into categories like "Marketing", "Software Development", "Events", etc. Each group contains related templates.

Response Structure: Returns an array of template group objects, each containing:

  • Group metadata (name, description, icon)
  • Array of templates belonging to that group

Sorting: Groups and templates within groups are sorted by their sort order.

Use Cases:

  • Displaying categorized template picker UI
  • Browsing templates by category
  • Understanding template organization
Authorizations:
personalAccessToken

Responses

Response samples

Content type
application/json
[
  • {
    }
]

timesheets

Timesheet management endpoints

Get timesheets

Retrieves timesheet data for the current user, showing tasks and their logged time entries.

Authentication required: Yes (Bearer token)

Permissions: Returns only the current user's timesheet data

Timesheet View: A timesheet groups tasks by project and shows time entries for each task within the specified date range.

Date Range:

  • Use start_date and end_date to specify the reporting period
  • If not provided, defaults may apply

Include Overdue: Use include_overdue=true to include tasks that are past their due date.

Project Filtering: Use project_ids (comma-separated) to filter timesheet to specific projects.

Response: Returns an array of timesheet entries with task and time information.

Use Cases:

  • Displaying weekly/monthly timesheets
  • Time tracking reports
  • Billing and invoicing data
  • Productivity analysis
Authorizations:
personalAccessToken
query Parameters
project_ids
string
Example: project_ids=920883

Comma-separated list of project IDs to filter timesheets

start_date
string <date>
Example: start_date=2023-11-13

Start date for the timesheet (YYYY-MM-DD format)

end_date
string <date>
Example: end_date=2023-11-13

End date for the timesheet (YYYY-MM-DD format)

include_overdue
boolean
Example: include_overdue=true

Whether to include overdue tasks

Responses

Response samples

Content type
application/json
[
  • { }
]

Set hours for a task on a specific date

Sets the time entry (in hours) for a specific task on a specific date.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the task

Path Parameters:

  • timesheetId: The task ID
  • Date is embedded in the path (format: YYYY-MM-DD)

Hours: Provide the total hours to log for this task on this date. This will create or update the time entry.

Use Cases:

  • Logging time from a timesheet view
  • Bulk time entry
  • Updating previously logged time

Response: Returns the created or updated time block.

Note: This endpoint uses an unusual path structure with the date embedded. The path should be: /timesheets/{taskId}/{date} where date is in YYYY-MM-DD format.

Authorizations:
personalAccessToken
path Parameters
timesheetId
required
integer
Example: 12345

ID of the task to log time for

Request Body schema: application/json
required
hours
required
number [ 0 .. 24 ]

Number of hours to log

Responses

Request samples

Content type
application/json
{
  • "hours": 5
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "task_id": 12345,
  • "start_date": "2020-06-11",
  • "end_date": "2020-06-11",
  • "hours": 5,
  • "resource_id": 123
}

times

Time tracking endpoints

List time blocks

Retrieves time blocks (time entries) for the current user or specified users.

Authentication required: Yes (Bearer token)

Query Parameters:

  • date: Get time blocks for a specific date (YYYY-MM-DD format)
  • user_ids: Comma-separated list of user IDs (defaults to current user)

Date Filtering: Use date parameter to get time blocks for a specific date.

User Filtering: Use user_ids (comma-separated) to get time blocks for specific users. Defaults to current user.

Permissions: Users can only view their own time blocks unless they have admin access to the projects.

Response: Returns an array of time block objects.

Note: For filtering by type (current, open, today), use the dedicated endpoints: GET /times/today, GET /times/current, or GET /times/open.

Authorizations:
personalAccessToken
query Parameters
user_ids
string
Example: user_ids=123,124

Comma-separated list of user IDs to get time blocks for (defaults to current user)

date
string <date>
Example: date=2009-12-25

Specific date to get time blocks for (YYYY-MM-DD format)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a time block

Creates a new time block (time entry).

Authentication required: Yes (Bearer token)

Create Time Block:

  • Provide task_id, start_time, and end_time
  • Creates a completed time entry
  • Optionally specify user_id to create time for another user (requires project admin)

Permissions:

  • Creating time for yourself: Requires access to the task
  • Creating time for others: Requires admin permissions on the project

Validation:

  • Task must exist and user must have access
  • Start time must be before end time

Response: Returns the newly created time block.

Note: To punch in (start an open time block), use POST /times/punch-in.

Authorizations:
personalAccessToken
Request Body schema: application/json
required
task_id
required
integer

ID of the task to log time for

start_time
string <date-time>

Start time (required for regular time blocks)

end_time
string <date-time>

End time (required for regular time blocks)

user_id
integer

Optional user ID to create time for (requires project admin, defaults to current user)

Responses

Request samples

Content type
application/json
Example
{
  • "task_id": 123,
  • "start_time": "2016-06-17T09:00:00Z",
  • "end_time": "2016-06-17T17:00:00Z"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "task_id": 123,
  • "start_date": "2016-06-17",
  • "end_date": "2016-06-17",
  • "hours": 8,
  • "resource_id": 123
}

Get today's time blocks

Retrieves all time blocks for today for the current user.

Authentication required: Yes (Bearer token)

Permissions: Returns only the current user's time blocks for today

Response: Returns an array of time block objects for today (including completed ones).

Authorizations:
personalAccessToken

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get current active time block

Retrieves the currently active (open) time block for today for the current user.

Authentication required: Yes (Bearer token)

Permissions: Returns only the current user's active time block

Current Time Block: Returns the open time block for today (excludes open blocks from previous days).

Response: Returns a single time block object if one is active, or 204 No Content if none.

Authorizations:
personalAccessToken

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "task_id": 23456789,
  • "start_date": "2024-01-15",
  • "end_date": null,
  • "hours": null,
  • "resource_id": 123
}

Get all open time blocks

Retrieves all unended (open) time blocks for the current user.

Authentication required: Yes (Bearer token)

Permissions: Returns only the current user's open time blocks

Open Time Blocks: Returns all time blocks that don't have an end time (includes open blocks from previous days).

Response: Returns an array of open time block objects.

Authorizations:
personalAccessToken

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Punch in (start a time block)

Starts an open time block (punch in) for a task.

Authentication required: Yes (Bearer token)

Punch In: Creates an open time block with no end time. The end time is set later with punch out.

Permissions: Requires access to the task

Validation:

  • Task must exist and user must have access
  • Cannot have overlapping open time blocks

Response: Returns the newly created time block.

Authorizations:
personalAccessToken
Request Body schema: application/json
required
task_id
required
integer

ID of the task to log time for

Responses

Request samples

Content type
application/json
{
  • "task_id": 123
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "task_id": 123,
  • "start_date": "2016-06-17",
  • "end_date": null,
  • "hours": null,
  • "resource_id": 123
}

Update a time block

Updates a time block's start time, end time, or associated task.

Authentication required: Yes (Bearer token)

Permissions: User must own the time block or have admin access to the project

Updateable Fields:

  • start_time: Change when the time block started
  • end_time: Change when the time block ended
  • task_id: Move the time block to a different task (requires access to new task)

Time Format: All times must be in ISO 8601 format (UTC)

Validation:

  • Start time must be before end time
  • Task must exist and user must have access

Response: Returns the updated time block.

Authorizations:
personalAccessToken
path Parameters
timeId
required
integer
Example: 12345

ID of the time block to update

Request Body schema: application/json
required
task_id
integer

New task ID to associate the time block with

start_time
string <date-time>

Updated start time

end_time
string <date-time>

Updated end time

Responses

Request samples

Content type
application/json
{
  • "start_time": "2009-01-01T09:00:00Z",
  • "end_time": "2009-01-01T17:00:00Z"
}

Response samples

Content type
application/json
{
  • "id": 78901,
  • "task_id": 23456789,
  • "start_date": "2024-01-15",
  • "end_date": "2024-01-17",
  • "hours": 24,
  • "resource_id": 1000
}

Delete a time block

Permanently deletes a time block.

Authentication required: Yes (Bearer token)

Permissions: User must own the time block or have admin access to the project

Warning: This operation cannot be undone. The time entry will be permanently removed.

Response: Returns 204 No Content on success.

Authorizations:
personalAccessToken
path Parameters
timeId
required
integer
Example: 12345

ID of the time block to delete

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Punch out of a time block

Ends an open time block by setting its end time (punch out).

Authentication required: Yes (Bearer token)

Permissions: User must own the time block or have admin access to the project

Punch Out: Sets the end time for an open time block that was created with punch in. The end time is set to the current timestamp.

Response: Returns the updated time block with the end time set.

Authorizations:
personalAccessToken
path Parameters
timeId
required
integer
Example: 12345

ID of the time block to punch out

Responses

Response samples

Content type
application/json
{
  • "id": 222,
  • "task_id": 123,
  • "start_date": "2024-01-17",
  • "end_date": "2024-01-17",
  • "hours": 8,
  • "resource_id": 123
}

webhooks

Webhook management endpoints

Create a webhook subscription

Creates a new webhook subscription to receive notifications when events occur on a project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to create webhooks on the target resource (project admin required)

Webhook Events: Subscribe to specific events:

  • task_created: When a task is created
  • task_updated: When a task is updated
  • task_deleted: When a task is deleted

Target Types: Currently only project is supported as a target type.

Webhook Delivery: When subscribed events occur, TeamGantt will send a POST request to your specified URL with event details in the request body.

URL Requirements:

  • Must be a valid HTTPS URL
  • Must be publicly accessible
  • Should respond with 2xx status code to acknowledge receipt

Response: Returns the newly created webhook subscription.

Authorizations:
personalAccessToken
Request Body schema: application/json
required
target_type
required
string
Value: "project"

Type of resource to monitor (currently only 'project' is supported)

target_id
required
integer

ID of the project to monitor

events
required
Array of strings non-empty
Items Enum: "task_created" "task_updated" "task_deleted"

Array of event types to subscribe to

url
required
string <uri> <= 2048 characters

Endpoint URL to receive webhook POST requests

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "target_type": "project",
  • "target_id": 1000,
  • "url": "https://example.com/webhook-endpoint",
  • "events": [
    ],
  • "created_by": 123,
  • "created_at": "2024-01-15T10:30:00Z"
}

List webhooks

Retrieves all webhook subscriptions created by the current user.

Authentication required: Yes (Bearer token)

Permissions: Returns only webhooks created by the current user

Response: Returns an array of webhook objects with their event subscriptions.

Authorizations:
personalAccessToken

Responses

Response samples

Content type
application/json
[
  • {
    }
]

workload

Workload management endpoints

Get workload for a user

Retrieves workload allocation data for a specific user, showing how many hours they have allocated across days.

Authentication required: Yes (Bearer token)

Permissions: Users can only view their own workload (userId must match current user)

Workload Calculation: Analyzes task assignments to calculate daily/weekly/monthly hour allocations based on:

  • Task duration
  • Task start and end dates
  • User's assigned percentage on each task
  • Working days (excludes weekends/holidays)

Grouping: Use group_by parameter to group results:

  • day: Daily breakdown (default)
  • week: Weekly totals
  • month: Monthly totals

Date Range: Use start_date and end_date to specify the analysis period.

Project Filtering: Use project_ids[] to limit analysis to specific projects.

Response: Returns a workload data object with type 'user' and daily/weekly/monthly hour allocations.

Authorizations:
personalAccessToken
path Parameters
userId
required
integer >= 1
Example: 123

Unique identifier of the user

query Parameters
group_by
string
Default: "day"
Enum: "day" "week" "month"
Example: group_by=day

How to group workload data

project_ids[]
Array of integers
Example: project_ids[]=920883

Filter to specific projects

start_date
string <date>
Example: start_date=2024-01-01

Start date for workload analysis

end_date
string <date>
Example: end_date=2024-01-31

End date for workload analysis

Responses

Response samples

Content type
application/json
{
  • "type": "user",
  • "type_id": 123,
  • "data": [
    ]
}

Get workload for multiple users

Retrieves workload allocation data for multiple users.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the specified users (must be in same company)

Required: At least one user ID must be provided via ids parameter.

Workload Calculation: For each user, calculates hour allocations based on task assignments.

Grouping: Use group_by to control aggregation:

  • day: Daily breakdown (default)
  • week: Weekly totals
  • month: Monthly totals

Date Range: Use start_date and end_date to specify the analysis period.

Project Filtering: Use project_ids or project_id to limit analysis to specific projects.

Response: Returns an array of workload data objects, one for each requested user.

Authorizations:
personalAccessToken
query Parameters
ids
required
string^[0-9]+(,[0-9]+)*$
Example: ids=1000

Comma-separated list of user IDs

group_by
string
Enum: "day" "week" "month"
Example: group_by=day

How to group workload data

project_id
string
Example: project_id=789012

Single project ID to filter (alternative to project_ids)

project_ids
string
Example: project_ids=123456,789012

Comma-separated list of project IDs

start_date
string <date>
Example: start_date=2024-01-01

Start date for workload analysis

end_date
string <date>
Example: end_date=2024-01-31

End date for workload analysis

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get workload for unassigned tasks

Retrieves workload data for tasks that have no resource assignments.

Authentication required: Yes (Bearer token)

Permissions: User must be authenticated and have access to projects

Unassigned Tasks: Identifies tasks that do not have any user or resource assignments, showing the "available" work that needs to be assigned.

Project Filtering:

  • Use project_ids (comma-separated) to filter to specific projects
  • If not provided, includes all active projects user has access to

Grouping: Use group_by to aggregate unassigned work:

  • day: Daily breakdown (default)
  • week: Weekly totals
  • month: Monthly totals

Use Cases:

  • Resource planning and allocation
  • Identifying tasks needing assignment
  • Capacity planning
  • Workload balancing

Response: Returns a workload data object with type 'unassigned' and hour allocations.

Authorizations:
personalAccessToken
query Parameters
project_ids
string^[0-9]+(,[0-9]+)*$
Example: project_ids=920883

Comma-separated list of project IDs to filter

group_by
string
Default: "day"
Enum: "day" "week" "month"
Example: group_by=day

How to group workload data

start_date
string <date>
Example: start_date=2024-01-01

Start date for workload analysis

end_date
string <date>
Example: end_date=2024-01-31

End date for workload analysis

Responses

Response samples

Content type
application/json
{
  • "type": "unassigned",
  • "type_id": null,
  • "data": [
    ]
}

Get workload for company resources

Retrieves workload allocation data for company resources (equipment, meeting rooms, etc.).

Authentication required: Yes (Bearer token)

Permissions: User must have access to the specified resources (must be in same company)

Required: At least one resource ID must be provided via ids parameter.

Workload Calculation: For each company resource, calculates hour allocations based on task assignments.

Parameters identical to user workload endpoint:

  • group_by: Daily/weekly/monthly aggregation
  • start_date / end_date: Date range
  • project_id / project_ids: Project filtering

Response: Returns an array of workload data objects, one for each requested company resource.

Authorizations:
personalAccessToken
query Parameters
ids
required
string^[0-9]+(,[0-9]+)*$
Example: ids=1000

Comma-separated list of company resource IDs

group_by
string
Enum: "day" "week" "month"
Example: group_by=day

How to group workload data

project_id
string
Example: project_id=920883

Single project ID to filter

start_date
string <date>
Example: start_date=2024-01-01

Start date for workload analysis

end_date
string <date>
Example: end_date=2024-01-31

End date for workload analysis

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get workload for project resources

Retrieves workload allocation data for project-specific resources.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the specified resources and their projects

Required: At least one resource ID must be provided via ids parameter.

Workload Calculation: For each project resource, calculates hour allocations based on task assignments.

Parameters identical to user and company resource workload endpoints:

  • group_by: Daily/weekly/monthly aggregation
  • start_date / end_date: Date range
  • project_id / project_ids: Project filtering

Response: Returns an array of workload data objects, one for each requested project resource.

Authorizations:
personalAccessToken
query Parameters
ids
required
string^[0-9]+(,[0-9]+)*$
Example: ids=1000

Comma-separated list of project resource IDs

group_by
string
Enum: "day" "week" "month"
Example: group_by=day

How to group workload data

project_id
string
Example: project_id=920883

Single project ID to filter

start_date
string <date>
Example: start_date=2024-01-01

Start date for workload analysis

end_date
string <date>
Example: end_date=2024-01-31

End date for workload analysis

Responses

Response samples

Content type
application/json
[
  • {
    }
]

teams

Add a team to a project

Adds a team to a project, granting all team members access with the specified permission level.

Authentication required: Yes (Bearer token)

Permissions: User must be a project admin

Team Requirements:

  • Team must belong to the same company as the project
  • Team cannot already be assigned to this project

Invitation Emails: By default, all team members will receive invitation emails. Set send_invite: false to skip sending emails.

Response: Returns the project team assignment with nested team and user information.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
team_id
required
string <uuid>

ID of the team to add

permission
required
string
Enum: "admin" "edit" "own_progress" "view_only"

Permission level to grant the team

message
string or null <= 1000 characters

Optional custom message to include in invitation emails sent to team members

send_invite
boolean
Default: true

Whether to send invitation emails to team members (defaults to true)

Responses

Request samples

Content type
application/json
{
  • "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  • "permission": "admin",
  • "message": "Welcome to the project!",
  • "send_invite": true
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "project_id": 920883,
  • "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  • "permission": "admin",
  • "team": {
    }
}

raci

Get RACI roles for a project

Retrieves all RACI (Responsible, Accountable, Consulted, Informed) role assignments for a project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

RACI Matrix: RACI is a responsibility assignment matrix used to clarify roles:

  • R (Responsible): Does the work
  • A (Accountable): Ultimately answerable for the task
  • C (Consulted): Provides input/advice
  • I (Informed): Kept up-to-date on progress

Response: Returns an array of RACI role assignments showing which users have which roles for each task, group, or project.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create or update RACI role assignment

Creates or updates a RACI role assignment for a user on a target resource (task, group, or project).

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Upsert Behavior: If a RACI assignment already exists for this user+target combination, it will be updated. Otherwise, a new assignment is created.

Roles:

  • Pass an array of role letters: ["R", "A", "C", "I"]
  • Roles are combined into a string (e.g., ["R", "A"] becomes "RA")
  • Pass empty array or null to remove all roles for this user+target
  • Order doesn't matter; roles are normalized

Validation:

  • target_type must be "task", "group", or "project"
  • resource_type must be "user" (currently only users are supported)
  • User (resource_id) must have access to the project
  • Target must exist and belong to the specified project

Response: Returns the created or updated RACI role assignment.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
project_id
required
integer

ID of the project

target_type
required
string
Enum: "task" "group" "project"

Type of target resource

target_id
required
integer

ID of the target resource

resource_type
required
string
Value: "user"

Type of resource (currently only 'user' is supported)

resource_id
required
integer

ID of the resource (user ID)

roles
required
Array of strings or null[ items^[RACI]$ ]
Enum: "R" "A" "C" "I"

Array of RACI role letters (R, A, C, I). Pass empty array or null to remove all roles.

Responses

Request samples

Content type
application/json
Example
{
  • "project_id": 1000,
  • "target_type": "task",
  • "target_id": 12345,
  • "resource_type": "user",
  • "resource_id": 1000,
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 1000,
  • "target_type": "task",
  • "target_id": 12345,
  • "resource_type": "user",
  • "resource_id": 1000,
  • "roles": "RA"
}

resources

Get all available resources for a project

Retrieves all resources that can be assigned to tasks in this project, including users, company resources, and project-specific resources.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Resource Types:

  • User Resources: Users from the company who can be assigned to tasks
  • Company Resources: Company-level resources (equipment, rooms, etc.) available to this project
  • Project Resources: Project-specific resources that only exist within this project

Response: Returns an object with three arrays, one for each resource type.

Use Cases:

  • Populating resource dropdowns in UI
  • Determining which resources can be assigned to tasks
  • Resource planning and allocation
Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
{
  • "user_resources": [
    ],
  • "company_resources": [
    ],
  • "project_resources": [
    ]
}

Get all resources for a project (alias)

Retrieves all resources available for a project. This is an alias for /projects/{projectId}/resource_options.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Response: Returns an object containing three resource types:

  • User resources (users from the company)
  • Company resources (company-level resources)
  • Project resources (project-specific resources)

Note: This endpoint is functionally identical to /projects/{projectId}/resource_options. Use that endpoint instead for consistency.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
{
  • "user_resources": [
    ],
  • "company_resources": [
    ],
  • "project_resources": [
    ]
}

List project-specific resources (labels)

Retrieves all project-specific resources (resources that exist only within this project, not company-wide).

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Response: Returns an array of project resource objects.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a project-specific resource (label)

Creates a new resource specific to this project (not shared with other projects).

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project and company

Resource Limit: Company must not have reached the maximum resources limit for their plan.

Use Cases:

  • Equipment unique to the project
  • Meeting rooms reserved for the project
  • Other project-specific assets

Response: Returns the newly created project resource.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Name of the resource

color
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Color identifier for the resource

Responses

Request samples

Content type
application/json
{
  • "name": "Project Resource",
  • "color": "green1"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "name": "Project Resource",
  • "color": "green1",
  • "created_at": "2024-01-15T10:30:00Z"
}

Get a project resource (legacy route - use resourceId instead)

Retrieves a specific project resource.

Note: This is a legacy route with incorrect path parameter naming. Use GET /projects/{projectId}/resources/project/{resourceId} instead.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "name": "Conference Room A",
  • "color": "blue1",
  • "created_at": "2024-01-15T10:30:00Z"
}

Update a project resource (legacy route)

Updates a project resource.

Note: This is a legacy route with incorrect path parameter naming. Use PATCH /projects/{projectId}/resources/project/{resourceId} instead.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Updated name of the resource

Responses

Request samples

Content type
application/json
{
  • "name": "Updated Resource"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "name": "Conference Room A",
  • "color": "blue1",
  • "created_at": "2024-01-15T10:30:00Z"
}

Delete a project resource (legacy route)

Deletes a project resource.

Note: This is a legacy route with incorrect path parameter naming. Use DELETE /projects/{projectId}/resources/project/{resourceId} instead.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get company resources (labels) for a project

Retrieves all company resources that have been added to this project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Response: Returns an array of company resource objects that are available for task assignments in this project.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add company resource (label) to project

Adds a company resource to a project with a project-specific color.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project and company

Resource Limit: Company must not have reached the maximum resources limit for their plan.

Response: Returns the newly created project-company resource link.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
company_resource_id
required
integer

ID of the company resource to add to the project

color
required
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Color identifier for this resource in the project context

Responses

Request samples

Content type
application/json
{
  • "company_resource_id": 1,
  • "color": "blue2"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "company_resource_id": 2754313,
  • "color": "blue1",
  • "resource": {
    }
}

Update company resource link (legacy route - use company_resource_optionId instead)

Updates a company resource link for a project.

Note: This is a legacy route. Use PATCH /projects/{projectId}/resources/company/{company_resource_optionId} instead.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

companyId
required
integer
Example: 12345

ID of the company resource link (use company_resource_optionId in the newer endpoint)

Request Body schema: application/json
required
company_resource_id
required
integer

ID of the company resource

color
required
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Updated color identifier for this resource

Responses

Request samples

Content type
application/json
{
  • "company_resource_id": 1,
  • "color": "blue2"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "company_resource_id": 2754313,
  • "color": "blue1",
  • "resource": {
    }
}

Remove company resource from project (legacy route)

Removes a company resource from a project.

Note: This is a legacy route. Use DELETE /projects/{projectId}/resources/company/{company_resource_optionId} instead.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

companyId
required
integer
Example: 12345

ID of the company resource link

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get workload for company resources

Retrieves workload allocation data for company resources (equipment, meeting rooms, etc.).

Authentication required: Yes (Bearer token)

Permissions: User must have access to the specified resources (must be in same company)

Required: At least one resource ID must be provided via ids parameter.

Workload Calculation: For each company resource, calculates hour allocations based on task assignments.

Parameters identical to user workload endpoint:

  • group_by: Daily/weekly/monthly aggregation
  • start_date / end_date: Date range
  • project_id / project_ids: Project filtering

Response: Returns an array of workload data objects, one for each requested company resource.

Authorizations:
personalAccessToken
query Parameters
ids
required
string^[0-9]+(,[0-9]+)*$
Example: ids=1000

Comma-separated list of company resource IDs

group_by
string
Enum: "day" "week" "month"
Example: group_by=day

How to group workload data

project_id
string
Example: project_id=920883

Single project ID to filter

start_date
string <date>
Example: start_date=2024-01-01

Start date for workload analysis

end_date
string <date>
Example: end_date=2024-01-31

End date for workload analysis

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get workload for project resources

Retrieves workload allocation data for project-specific resources.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the specified resources and their projects

Required: At least one resource ID must be provided via ids parameter.

Workload Calculation: For each project resource, calculates hour allocations based on task assignments.

Parameters identical to user and company resource workload endpoints:

  • group_by: Daily/weekly/monthly aggregation
  • start_date / end_date: Date range
  • project_id / project_ids: Project filtering

Response: Returns an array of workload data objects, one for each requested project resource.

Authorizations:
personalAccessToken
query Parameters
ids
required
string^[0-9]+(,[0-9]+)*$
Example: ids=1000

Comma-separated list of project resource IDs

group_by
string
Enum: "day" "week" "month"
Example: group_by=day

How to group workload data

project_id
string
Example: project_id=920883

Single project ID to filter

start_date
string <date>
Example: start_date=2024-01-01

Start date for workload analysis

end_date
string <date>
Example: end_date=2024-01-31

End date for workload analysis

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get company resources (labels) available for a project

Retrieves all company-level resources that can be assigned to tasks in this project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Company Resources: These are resources defined at the company level (equipment, meeting rooms, etc.) that can be shared across multiple projects within the company.

Response: Returns an array of company resource objects. These resources can be added to the project using POST /projects/{projectId}/resources/company.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add company resource (label) to project

Adds a company resource to a project, making it available for task assignments.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project and company

Company Resource: The resource must already exist at the company level and belong to the same company as the project.

Color: Each project can assign a custom color to a company resource, overriding the company-level color for this specific project context.

Response: Returns the newly created project-company resource link with the assigned color.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
company_resource_id
required
integer

ID of the company resource to add to the project

color
required
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Color identifier for this resource in the project context

Responses

Request samples

Content type
application/json
{
  • "company_resource_id": 2754313,
  • "color": "blue2"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "company_resource_id": 2754313,
  • "color": "blue2",
  • "resource": {
    }
}

List project-specific resources (labels) (alias)

Retrieves all project-specific resources. This is an alias for /projects/{projectId}/resources/project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Note: Use /projects/{projectId}/resources/project instead for consistency.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a project-specific resource (alias)

Creates a new project-specific resource. This is an alias for POST /projects/{projectId}/resources/project.

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project and company

Note: Use /projects/{projectId}/resources/project instead for consistency.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Name of the resource

color
string
Enum: "blue1" "blue2" "blue3" "brown1" "green1" "green2" "green3" "grey1" "magenta1" "milestone" "orange1" "orange2" "pink1" "purple1" "purple2" "red1" "yellow1"

Color identifier for the resource

Responses

Request samples

Content type
application/json
{
  • "name": "Rick Resource",
  • "color": "blue1"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "name": "Conference Room A",
  • "color": "blue1",
  • "created_at": "2024-01-15T10:30:00Z"
}

Get a project resource (label)

Retrieves a specific project resource by ID.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Project Resources: These are resources specific to the project (not company-wide).

Response: Returns the project resource object with name and color.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

resourceId
required
integer >= 1
Example: 1000

Unique identifier of the resource assigned to a task

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "name": "Conference Room A",
  • "color": "blue2",
  • "created_at": "2024-01-15T10:30:00Z"
}

Update a project resource (label)

Updates a project resource's properties (name and/or color).

Authentication required: Yes (Bearer token)

Permissions: User must have edit permissions on the project

Updateable Fields:

  • name: Resource name (required in request)

Response: Returns the updated project resource object.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

resourceId
required
integer >= 1
Example: 1000

Unique identifier of the resource assigned to a task

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Updated name of the resource

Responses

Request samples

Content type
application/json
{
  • "name": "Test POST Project Resource Name Update"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "project_id": 920883,
  • "name": "Test POST Project Resource Name Update",
  • "color": "blue2",
  • "created_at": "2024-01-15T10:30:00Z"
}

timeblocks

List time blocks for a project

Retrieves all time blocks (time entries) for tasks within a project.

Authentication required: Yes (Bearer token)

Permissions: User must have access to the project

Time Blocks: Time blocks represent logged time on tasks, including start time, end time, and the user who logged the time.

Pagination: Use offset and limit query parameters to paginate results.

  • Default limit: 100
  • Maximum limit: 100

Response: Returns a paginated list of time block objects.

Authorizations:
personalAccessToken
path Parameters
projectId
required
integer >= 1
Example: 920883

Unique identifier of the project

query Parameters
offset
integer >= 0
Default: 0

Pagination offset

limit
integer [ 1 .. 100 ]
Default: 100
Example: limit=100

Maximum number of time blocks to return

page
integer >= 1
Example: page=1

Page number (alternative to offset)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

export

Export projects to CSV

Exports one or more projects to CSV format, generating a downloadable file with project and task data.

Authentication required: Yes (Bearer token)

Permissions: User must have access to all specified projects

Export Contents:

  • Project information
  • All groups and tasks
  • Task dates, progress, assignments
  • Resources
  • Dependencies

Multiple Projects: Can export multiple projects in a single CSV file by providing multiple IDs.

Timeout: A 2-minute timeout is enforced due to potentially large data export.

Response: Returns a document object with a URL to download the generated CSV file.

Authorizations:
personalAccessToken
query Parameters
ids[]
required
Array of integers
Example: ids[]=920883

Array of project IDs to export

Responses

Response samples

Content type
application/json
{}

users

Get workload for a user

Retrieves workload allocation data for a specific user, showing how many hours they have allocated across days.

Authentication required: Yes (Bearer token)

Permissions: Users can only view their own workload (userId must match current user)

Workload Calculation: Analyzes task assignments to calculate daily/weekly/monthly hour allocations based on:

  • Task duration
  • Task start and end dates
  • User's assigned percentage on each task
  • Working days (excludes weekends/holidays)

Grouping: Use group_by parameter to group results:

  • day: Daily breakdown (default)
  • week: Weekly totals
  • month: Monthly totals

Date Range: Use start_date and end_date to specify the analysis period.

Project Filtering: Use project_ids[] to limit analysis to specific projects.

Response: Returns a workload data object with type 'user' and daily/weekly/monthly hour allocations.

Authorizations:
personalAccessToken
path Parameters
userId
required
integer >= 1
Example: 123

Unique identifier of the user

query Parameters
group_by
string
Default: "day"
Enum: "day" "week" "month"
Example: group_by=day

How to group workload data

project_ids[]
Array of integers
Example: project_ids[]=920883

Filter to specific projects

start_date
string <date>
Example: start_date=2024-01-01

Start date for workload analysis

end_date
string <date>
Example: end_date=2024-01-31

End date for workload analysis

Responses

Response samples

Content type
application/json
{
  • "type": "user",
  • "type_id": 123,
  • "data": [
    ]
}