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"
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:
| status | string Default: "active" Enum: "active" "closed" Example: status=active Filter boards by status |
[- {
- "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
}, - {
- "id": "1715b9b5-c5d7-4890-b123-4567890bcdef",
- "name": "Marketing Board",
- "company_id": 123456,
- "status": "active",
- "user_id": 124,
- "created_at": "2024-01-12T11:00:00Z",
- "is_starred": false
}
]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:
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 |
{- "name": "Project Board",
- "company_id": 123456
}{- "id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "name": "Project Board",
- "company_id": 123456,
- "status": "active",
- "user_id": 123,
- "created_at": "2024-01-17T10:30:00Z",
- "is_starred": true
}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:
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 |
{- "name": "Column 1",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73"
}{- "id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "name": "Column 1",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "sort": 1,
- "auto_move_cards": false,
- "auto_set_task_progress": null
}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:
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 taskUse cases:
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 |
{- "column_id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "target_type": "task",
- "target_id": 12345678,
- "sort": 1
}{- "id": "c3d4e5f6-a7b8-4901-a234-56789abcdef0",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "column_id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "target_type": "task",
- "target_id": 12345678,
- "sort": 1
}Retrieves a single board, including its columns, cards, users and teams.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the board
Use cases:
| boardId required | string <uuid> Example: 0604a8a4-d4b4-48db-9106-9db0d1b11b73 Unique identifier of the board (UUID) |
{- "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,
- "columns": [
- {
- "id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "name": "In Progress",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "sort": 2,
- "auto_move_cards": true,
- "auto_set_task_progress": 50,
- "cards": [
- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "column_id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "target_type": "task",
- "target_id": 23456789,
- "sort": 1
}
]
}
], - "users": [
- {
- "id": 12345,
- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "time_zone": "-05:00",
- "today_date": "2024-01-15",
- "status": "active",
- "daily_email_hour": 9,
- "daily_project_summary_subscribed": true,
- "companies": [
- { }
], - "integrations": [
- { }
], - "integrationsNew": [
- { }
], - "preferencesNew": { },
- "preferences": { },
- "notifications": { },
- "mobile_notifications": { },
- "metrics": { },
- "welcome_survey": { },
- "created_at": "2024-01-01T00:00:00Z"
}
], - "teams": [
- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
]
}Renames, closes/reopens or stars/unstars a board. All fields are optional.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the board
Note: Starring is per-user and does not affect other users.
| boardId required | string <uuid> Example: 0604a8a4-d4b4-48db-9106-9db0d1b11b73 Unique identifier of the board (UUID) |
| name | string New name of the board |
| status | string Enum: "active" "closed" Set to |
| is_starred | boolean Whether to star the board for the current user |
{- "name": "Renamed Board",
- "status": "closed",
- "is_starred": true
}{- "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,
- "columns": [
- {
- "id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "name": "In Progress",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "sort": 2,
- "auto_move_cards": true,
- "auto_set_task_progress": 50,
- "cards": [
- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "column_id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "target_type": "task",
- "target_id": 23456789,
- "sort": 1
}
]
}
], - "users": [
- {
- "id": 12345,
- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "time_zone": "-05:00",
- "today_date": "2024-01-15",
- "status": "active",
- "daily_email_hour": 9,
- "daily_project_summary_subscribed": true,
- "companies": [
- { }
], - "integrations": [
- { }
], - "integrationsNew": [
- { }
], - "preferencesNew": { },
- "preferences": { },
- "notifications": { },
- "mobile_notifications": { },
- "metrics": { },
- "welcome_survey": { },
- "created_at": "2024-01-01T00:00:00Z"
}
], - "teams": [
- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
]
}Lists users who have been granted access to a board.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the board
| boardId required | string <uuid> Example: 0604a8a4-d4b4-48db-9106-9db0d1b11b73 Unique identifier of the board (UUID) |
[- {
- "id": 12345,
- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "time_zone": "-05:00",
- "today_date": "2024-01-15",
- "status": "active",
- "daily_email_hour": 9,
- "daily_project_summary_subscribed": true,
- "companies": [
- { }
], - "integrations": [
- { }
], - "integrationsNew": [
- { }
], - "preferencesNew": { },
- "preferences": { },
- "notifications": { },
- "mobile_notifications": { },
- "metrics": { },
- "welcome_survey": { },
- "created_at": "2024-01-01T00:00:00Z"
}
]Grants a single user access to a board, optionally emailing an invitation.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the board
Validation: The user must belong to the board's company, must not be a guest, and must not already have access.
| boardId required | string <uuid> Example: 0604a8a4-d4b4-48db-9106-9db0d1b11b73 Unique identifier of the board (UUID) |
| user_id required | integer ID of a non-guest user in the board's company |
| send_invite | boolean Whether to email the user an invitation |
| message | string or null Optional message to include in the invitation |
{- "user_id": 123,
- "send_invite": true,
- "message": "Welcome to the board!"
}{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Replaces the complete set of users with access to a board. Users not included in users lose access.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the board
Invitations: With send_invite: true, only newly added users are emailed.
| boardId required | string <uuid> Example: 0604a8a4-d4b4-48db-9106-9db0d1b11b73 Unique identifier of the board (UUID) |
| users required | Array of integers IDs of non-guest company users who should have access. Users not listed lose access. |
| send_invite | boolean Whether to email an invitation to newly added users |
| message | string or null Optional message to include in the invitation |
{- "users": [
- 123,
- 124
], - "send_invite": false
}{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Emails invitations to users who already have access to the board.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the board
Validation: Every ID in users must already have access to the board.
| boardId required | string <uuid> Example: 0604a8a4-d4b4-48db-9106-9db0d1b11b73 Unique identifier of the board (UUID) |
| users required | Array of integers IDs of users who already have access to the board |
| message | string or null Optional message to include in the invitation |
{- "users": [
- 123,
- 124
], - "message": "Reminder to check the board"
}{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Revokes a user's access to a board.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the board
| boardId required | string <uuid> Example: 0604a8a4-d4b4-48db-9106-9db0d1b11b73 Unique identifier of the board (UUID) |
| userId required | integer >= 1 Example: 123 Unique identifier of the user |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Lists teams that have been granted access to a board.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the board
| boardId required | string <uuid> Example: 0604a8a4-d4b4-48db-9106-9db0d1b11b73 Unique identifier of the board (UUID) |
[- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
]Grants a team access to a board, optionally emailing every team member.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the board
Validation: The team must belong to the board's company and must not already have access.
| boardId required | string <uuid> Example: 0604a8a4-d4b4-48db-9106-9db0d1b11b73 Unique identifier of the board (UUID) |
| team_id required | string <uuid> ID of a team belonging to the board's company |
| send_invite | boolean Whether to email every member of the team an invitation |
| message | string or null Optional message to include in the invitation |
{- "team_id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "send_invite": true
}{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Revokes a team's access to a board.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the board
Note: Returns 404 if the team did not have access to the board.
| boardId required | string <uuid> Example: 0604a8a4-d4b4-48db-9106-9db0d1b11b73 Unique identifier of the board (UUID) |
| teamId required | string <uuid> Example: a1b2c3d4-e5f6-4789-a012-3456789abcde Unique identifier of the team (UUID) |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Updates a column's name, position or automation rules. All fields are optional.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the board
Automation: With auto_move_cards, cards move to this column based on task progress. auto_set_task_progress sets a task's progress when its card is moved here.
| columnId required | string <uuid> Example: 544b6464-b8fd-489e-8ef0-651b855e6c13 Unique identifier of the column (UUID) |
| name | string <= 255 characters New name of the column |
| sort | integer New sort order of the column on the board |
| auto_move_cards | boolean Whether cards automatically move to this column based on task progress |
| auto_set_task_progress | integer or null [ 0 .. 100 ] Progress percentage to set on a task when its card moves to this column. Use null to disable. |
{- "name": "In Review",
- "sort": 3,
- "auto_move_cards": true,
- "auto_set_task_progress": 50
}{- "id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "name": "In Progress",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "sort": 2,
- "auto_move_cards": true,
- "auto_set_task_progress": 50
}Deletes a column from a board.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the board
Constraint: Some columns (for example those with automation rules) can't be deleted while they still contain cards. In that case the API returns 400 and the cards must be moved or deleted first.
| columnId required | string <uuid> Example: 544b6464-b8fd-489e-8ef0-651b855e6c13 Unique identifier of the column (UUID) |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}Changes a card's position, and optionally moves it to a different column.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the card's board
Note: sort is required even when only moving columns.
| cardId required | string <uuid> Example: a1b2c3d4-e5f6-4789-a012-3456789abcde Unique identifier of the card (UUID) |
| sort required | integer New sort order within the column |
| column_id | string <uuid> ID of the column to move the card to |
{- "column_id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "sort": 2
}{- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "column_id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "target_type": "task",
- "target_id": 23456789,
- "sort": 1
}Removes a card from its board. The underlying task is not deleted.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the card's board
| cardId required | string <uuid> Example: a1b2c3d4-e5f6-4789-a012-3456789abcde Unique identifier of the card (UUID) |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}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:
Calculation: For each board, the endpoint:
Response: Returns an array of health report objects, one for each requested board.
| ids[] | Array of strings <uuid> [ items <uuid > ] Example: ids[]=443c80e4-72dc-4363-afd8-b58e6d866b63 Array of board IDs (UUIDs) to generate health reports for |
[- {
- "id": "443c80e4-72dc-4363-afd8-b58e6d866b63",
- "task_status": {
- "on_schedule": 15,
- "overdue": 3,
- "behind": 2,
- "upcoming": 10
}, - "percent_complete": 62.5
}
]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.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
[- {
- "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,
- "columns": [
- {
- "id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "name": "In Progress",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "sort": 2,
- "auto_move_cards": true,
- "auto_set_task_progress": 50,
- "cards": [
- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "column_id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "target_type": "task",
- "target_id": 23456789,
- "sort": 1
}
]
}
], - "users": [
- {
- "id": 12345,
- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "time_zone": "-05:00",
- "today_date": "2024-01-15",
- "status": "active",
- "daily_email_hour": 9,
- "daily_project_summary_subscribed": true,
- "companies": [
- { }
], - "integrations": [
- { }
], - "integrationsNew": [
- { }
], - "preferencesNew": { },
- "preferences": { },
- "notifications": { },
- "mobile_notifications": { },
- "metrics": { },
- "welcome_survey": { },
- "created_at": "2024-01-01T00:00:00Z"
}
], - "teams": [
- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
]
}
]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:
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.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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)
| |||||||
{- "columns": [
- {
- "name": "To Do",
- "auto_move_cards": false,
- "auto_set_task_progress": null
}, - {
- "name": "In Progress",
- "auto_move_cards": true,
- "auto_set_task_progress": 50
}, - {
- "name": "Done",
- "auto_move_cards": true,
- "auto_set_task_progress": 100
}
]
}{- "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,
- "columns": [
- {
- "id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "name": "In Progress",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "sort": 2,
- "auto_move_cards": true,
- "auto_set_task_progress": 50,
- "cards": [
- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "column_id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "target_type": "task",
- "target_id": 23456789,
- "sort": 1
}
]
}
], - "users": [
- {
- "id": 12345,
- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "time_zone": "-05:00",
- "today_date": "2024-01-15",
- "status": "active",
- "daily_email_hour": 9,
- "daily_project_summary_subscribed": true,
- "companies": [
- { }
], - "integrations": [
- { }
], - "integrationsNew": [
- { }
], - "preferencesNew": { },
- "preferences": { },
- "notifications": { },
- "mobile_notifications": { },
- "metrics": { },
- "welcome_survey": { },
- "created_at": "2024-01-01T00:00:00Z"
}
], - "teams": [
- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
]
}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:
[- {
- "id": 12345,
- "name": "My Projects (Active, Page 2)",
- "user_id": 123
}, - {
- "id": 12346,
- "name": "Team Tasks This Week",
- "user_id": 123
}
]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:
Use cases:
Bookmark data to create
| name required | string [ 1 .. 100 ] characters Display name for the bookmark |
| url required | string <uri> <= 2048 characters URL to bookmark |
{- "name": "My Projects (Active, Page 2)",
}{- "id": 12347,
- "name": "My Projects (Active, Page 2)",
- "user_id": 123
}Retrieves details of a single bookmark by its ID.
Authentication required: Yes (Bearer token)
Permissions: User can only access their own bookmarks
| bookmarkId required | integer >= 1 Example: 12345 Unique identifier of the bookmark |
{- "id": 12345,
- "name": "My Tasks",
- "user_id": 123
}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:
| bookmarkId required | integer >= 1 Example: 12345 Unique identifier of the bookmark |
Fields to update (partial update supported)
| name | string [ 1 .. 100 ] characters Updated display name |
| url | string <uri> <= 2048 characters Updated URL |
{- "name": "My Tasks - Updated"
}{- "id": 12345,
- "name": "My Tasks - Updated",
- "user_id": 123
}Permanently deletes a bookmark.
Authentication required: Yes (Bearer token)
Permissions: User can only delete their own bookmarks
Warning: This action cannot be undone.
| bookmarkId required | integer >= 1 Example: 12345 Unique identifier of the bookmark |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}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
| 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) |
[- {
- "id": 54321,
- "message": "This is a pinned comment",
- "type": "comment",
- "created_at": "2024-01-15T10:30:00Z",
- "updated_at": "2024-01-15T14:45:00Z",
- "pinned": true,
- "user_id": 123,
- "user_name": "John Doe",
- "attached_documents": [
- 456,
- 789
]
}, - {
- "id": 54320,
- "message": "This is a regular note",
- "type": "note",
- "created_at": "2024-01-14T09:15:00Z",
- "updated_at": "2024-01-14T09:15:00Z",
- "pinned": false,
- "user_id": 124,
- "user_name": "Jane Smith",
- "attached_documents": [ ]
}
]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
| 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) |
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) |
{- "message": "Here is a simple comment.",
- "type": "comment"
}{- "id": 54322,
- "message": "Here is an example comment with some attached documents.",
- "type": "comment",
- "created_at": "2024-01-15T16:20:00Z",
- "updated_at": "2024-01-15T16:20:00Z",
- "pinned": false,
- "user_id": 123,
- "user_name": "John Doe",
- "attached_documents": [
- 123,
- 456
]
}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
| 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 |
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 |
{- "message": "Here is an updated comment with corrected information."
}{- "id": 54321,
- "message": "Here is an updated comment with corrected information.",
- "type": "comment",
- "created_at": "2024-01-15T10:30:00Z",
- "updated_at": "2024-01-15T16:45:00Z",
- "pinned": false,
- "user_id": 123,
- "user_name": "John Doe",
- "attached_documents": [
- 123,
- 456
]
}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
| 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 |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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
| 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 |
Pin status to set
| pinned required | boolean Set to true to pin the comment, false to unpin it |
{- "pinned": true
}{- "id": 54321,
- "message": "This is an important comment",
- "type": "comment",
- "created_at": "2024-01-15T10:30:00Z",
- "updated_at": "2024-01-15T16:50:00Z",
- "pinned": true,
- "user_id": 123,
- "user_name": "John Doe",
- "attached_documents": [ ]
}Unpins a comment. Equivalent to POST with pinned: false, but needs no request body.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the target resource
target is tasks, groups or projects.
| 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 |
{- "id": 54321,
- "message": "Here is an example comment with some attached documents.",
- "type": "comment",
- "created_at": "2024-01-15T10:30:00Z",
- "updated_at": "2024-01-15T14:45:00Z",
- "pinned": false,
- "user_id": 123,
- "user_name": "John Doe",
- "attached_documents": [
- 123,
- 456
]
}Marks every comment on the target as read for the current user.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the target resource
target is tasks, groups or projects.
| 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) |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Marks every comment on the target as unread for the current user.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the target resource
target is tasks, groups or projects.
| 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) |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Marks a single comment as read for the current user.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the target resource
target is tasks, groups or projects.
| 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 |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Lists the users who can be @-mentioned in a comment on the target. Each entry includes the text to insert (mention_name) and basic profile details.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the target resource
targetType is tasks, groups or projects.
| targetId required | integer >= 1 Example: 12345 Unique identifier of the target resource (task, group, or project) |
| targetType required | string Enum: "tasks" "groups" "projects" Example: tasks Type of resource to mention users on |
[- {
- "mention_name": "@jdoe",
- "user_id": 123,
- "first_name": "Jane",
- "last_name": "Doe",
- "email_address": "jane@example.com",
}
]Adds the current user's reaction to a comment.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the comment's target
Conflicts: Returns 409 if the user already reacted with this option.
| commentId required | integer >= 1 Example: 54321 Unique identifier of the comment |
| reaction_option_id required | integer ID of the reaction option to add |
{- "reaction_option_id": 1
}{- "id": 789,
- "comment_id": 54321,
- "reaction_option_id": 1,
- "user_id": 123
}Removes a reaction from a comment.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the comment, and may only remove their own reactions unless they manage the project.
| commentId required | integer >= 1 Example: 54321 Unique identifier of the comment |
| reactionId required | integer >= 1 Example: 789 Unique identifier of the comment reaction |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Lists the emoji reactions available in a company: the built-in defaults (company_id is null) plus any custom ones the company has added.
Authentication required: Yes (Bearer token)
Permissions: User must be able to view the company
| id required | integer >= 1 Example: 123456 Company ID |
[- {
- "id": 1,
- "name": "thumbs_up",
- "company_id": null
}
]Deletes a company's custom reaction option.
Authentication required: Yes (Bearer token)
Permissions: User must be able to edit the owning company
Note: Default reactions (those with a null company_id) can't be deleted; the API returns 401.
| id required | integer >= 1 Example: 1 Reaction option ID |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Adds a custom reaction to a company.
Authentication required: Yes (Bearer token)
Permissions: User must be able to edit the company
Conflicts: Returns 409 if the company already has a reaction with the same name.
| name required | string |
| image_path required | string |
| company_id required | integer Company that will own the reaction |
{- "name": "celebrate",
- "company_id": 123456
}{- "id": 1,
- "name": "thumbs_up",
- "company_id": null
}Retrieves all users in a company.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the company
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
[- {
- "id": 123,
- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Smith",
- "permissions": "basic",
- "status": "active",
- "is_disabled": false,
- "time_zone": "-05:00"
}
]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
SSO note: If the company is configured for SSO via an identity provider, user invites/additions through this endpoint are forbidden and will return a 403 Forbidden response (error code: add_users_through_sso_provider).
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| 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 |
{- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Smith",
- "permissions": "basic",
- "send_invite": false
}{- "id": 123,
- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Smith",
- "permissions": "basic",
- "status": "active",
- "is_disabled": false,
- "time_zone": "-05:00"
}Retrieves details of a specific user in the company.
Authentication required: Yes (Bearer token)
Permissions: User must have manage access to the company
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| userId required | integer >= 1 Example: 123 Unique identifier of the user |
{- "id": 123,
- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Smith",
- "permissions": "basic",
- "status": "active",
- "is_disabled": false,
- "time_zone": "-05:00"
}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: Name and email can only be updated for pending users
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| userId required | integer >= 1 Example: 123 Unique identifier of the user |
| first_name | string Updated first name (only for pending users) |
| last_name | string Updated last name (only for pending users) |
| 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 |
{- "permissions": "edit",
- "is_disabled": false
}{- "id": 123,
- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Smith",
- "permissions": "basic",
- "status": "active",
- "is_disabled": false,
- "time_zone": "-05:00"
}Removes a user from the company.
Authentication required: Yes (Bearer token)
Permissions: User must have manage access; cannot remove self
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| userId required | integer >= 1 Example: 123 Unique identifier of the user |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Retrieves all resources including users, company resources, and project resources.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the company
NEW: As of v1.2.44, company-level access control is enforced; only users with explicit company access can view resources. This applies across all resource endpoints.
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
{- "user_resources": [
- { }
], - "company_resources": [
- {
- "id": 5000,
- "company_id": 123456,
- "name": "Conference Room A",
- "created_at": "2024-01-10T09:00:00Z"
}
], - "project_resources": [
- { }
]
}Retrieves all company-level resources (equipment, rooms, etc.).
Authentication required: Yes (Bearer token)
Permissions: User must have access to the company
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
[- {
- "id": 5000,
- "company_id": 123456,
- "name": "Conference Room A",
- "created_at": "2024-01-10T09:00:00Z"
}
]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
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| name required | string non-empty Name of the resource |
{- "name": "My Company"
}{- "id": 5000,
- "company_id": 123456,
- "name": "Conference Room A",
- "created_at": "2024-01-10T09:00:00Z"
}Updates a company resource name.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the company
| 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 |
| name required | string |
{- "name": "Example"
}{- "id": 5000,
- "company_id": 123456,
- "name": "Conference Room A",
- "created_at": "2024-01-10T09:00:00Z"
}Permanently deletes a company resource.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the company
| 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 |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Retrieves all project-level resources associated with the company.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the company
NEW: Company-level access is fully enforced; the requesting user must have view access to the company to see project resources.
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
[- { }
]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
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| year | string^\d{4}$ Example: year=2020 Filter by year (YYYY format) |
[- {
- "id": 12345,
- "company_id": 123456,
- "name": "Christmas",
- "year": "2025",
- "month": 12,
- "day": 25
}
]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
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| year | string^\d{4}$ Example: year=2020 Filter by year (YYYY format) |
| 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) |
{- "name": "Christmas",
- "year": "2025",
- "month": 12,
- "day": 25
}{- "id": 12345,
- "company_id": 123456,
- "name": "Christmas",
- "year": "2025",
- "month": 12,
- "day": 25
}Permanently deletes a holiday from the company.
Authentication required: Yes (Bearer token)
Permissions: User must have manage permissions on the company
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| holidayId required | integer >= 1 Example: 12345 Unique identifier of the holiday |
| year | string^\d{4}$ Example: year=2020 Filter by year (YYYY format) |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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.
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
[- {
- "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"
}
]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.
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| 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 |
{- "name": "Standard Meeting Notes",
- "note": "Meeting Date: {{date}}\nAttendees: {{attendees}}\nNotes:",
- "is_private": false
}{- "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"
}Updates an existing note template.
Authentication required: Yes (Bearer token)
Permissions:
Updateable Fields:
name: Template namenote: Template contentis_private: Whether the template is privateResponse: Returns the updated note template.
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| noteTemplateId required | string Example: template-abc-123 Unique identifier of the note template |
| name | string Template name |
| note | string Template content |
| is_private | boolean Whether the template is private to the creator |
{- "name": "Updated Meeting Notes",
- "note": "Meeting Date: {{date}}\nAttendees: {{attendees}}\nNotes:\n{{notes}}",
- "is_private": false
}{- "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"
}Permanently deletes a note template.
Authentication required: Yes (Bearer token)
Permissions:
Warning: This operation cannot be undone.
Response: Returns 204 No Content on success.
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| noteTemplateId required | string Example: template-abc-123 Unique identifier of the note template |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Retrieves detailed information about a specific company.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the company
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
{- "id": 123456,
- "name": "Example Company",
- "created_at": "2024-01-01T00:00:00Z"
}Updates company information. Supports partial updates.
Authentication required: Yes (Bearer token)
Permissions: User must have manage permissions on the company
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| name | string Updated company name |
{- "name": "Example Company Name"
}{- "id": 123456,
- "name": "Example Company",
- "created_at": "2024-01-01T00:00:00Z"
}Retrieves all projects within a company.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the company
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
{- "total": 25,
- "count": 25,
- "current_page": 1,
- "projects": [
- {
- "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": [
- 1,
- 2,
- 3,
- 4,
- 5
], - "public_key": null,
- "permission": "admin",
- "is_starred": false,
- "created_at": "2024-01-01T00:00:00Z",
- "accesses": [
- {
- "id": 7070608,
- "project_id": 920884,
- "company_id": 1000,
- "user_id": 1960234,
- "user": { },
- "permission": "edit",
- "status": "Accepted",
- "project_status": "active",
- "color": "blue1",
- "custom_message": "Join the party!"
}
], - "teams": [
- {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "permission": "admin",
- "team": {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
}
], - "company": { },
- "integrations": [
- { }
], - "metrics": { },
- "custom_fields": [
- {
- "id": 1001,
- "name": "PO Number",
- "type": "text",
- "options": [
- "A",
- "B"
], - "description": "Field for storing PO numbers"
}
]
}
]
}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
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
[- {
- "id": "f1a2b3c4-d5e6-4789-a012-3456789abcde",
- "name": "Q1 2024 Projects",
- "company_id": 123456,
- "user_id": 123,
- "is_starred": true
}
]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
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| 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 |
{- "name": "Example Folder Name",
- "is_starred": true
}{- "id": "f1a2b3c4-d5e6-4789-a012-3456789abcde",
- "name": "Q1 2024 Projects",
- "company_id": 123456,
- "user_id": 123,
- "is_starred": true
}Retrieves all teams in a company.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the company; filtered by team read permission
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
[- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
]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
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| 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) |
{- "name": "Development Team"
}{- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}Retrieves a team and its members.
Authentication required: Yes (Bearer token)
Permissions: User must be able to read the team
Plan: Requires a plan that includes the Teams feature.
| teamId required | string <uuid> Example: a1b2c3d4-e5f6-4789-a012-3456789abcde Unique identifier of the team (UUID) |
{- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456
}Updates a team's name.
Authentication required: Yes (Bearer token)
Permissions: User must be able to manage the company
Validation: Name is at most 100 characters and unique within the company.
Plan: Requires a plan that includes the Teams feature.
| teamId required | string <uuid> Example: a1b2c3d4-e5f6-4789-a012-3456789abcde Unique identifier of the team (UUID) |
| name | string [ 1 .. 100 ] characters New team name (unique within the company) |
{- "name": "Platform Team"
}{- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456
}Deletes a team. Members lose any task assignments they only had through the team; this cleanup runs in the background.
Authentication required: Yes (Bearer token)
Permissions: User must be able to manage the company
Plan: Requires a plan that includes the Teams feature.
| teamId required | string <uuid> Example: a1b2c3d4-e5f6-4789-a012-3456789abcde Unique identifier of the team (UUID) |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Adds a company user to a team.
Authentication required: Yes (Bearer token)
Permissions: User must be able to manage the company
Validation: The user must belong to the company, must not be a guest, and must not already be on the team.
Plan: Requires a plan that includes the Teams feature.
| teamId required | string <uuid> Example: a1b2c3d4-e5f6-4789-a012-3456789abcde Unique identifier of the team (UUID) |
| user_id required | integer ID of a non-guest user in the team's company |
{- "user_id": 123
}{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Removes a user from a team.
Authentication required: Yes (Bearer token)
Permissions: User must be able to manage the company
Validation: The user must currently be on the team.
Plan: Requires a plan that includes the Teams feature.
| teamId required | string <uuid> Example: a1b2c3d4-e5f6-4789-a012-3456789abcde Unique identifier of the team (UUID) |
| userId required | integer >= 1 Example: 123 Unique identifier of the user |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Replaces the company's logo. The previous logo is deleted.
Authentication required: Yes (Bearer token)
Permissions: User must be able to manage the company
Allowed formats: jpeg, jpg, gif, png. Other formats return 400 with extension_not_allowed.
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| file required | string <binary> Image file (jpeg, jpg, gif or png) |
{
}Retrieves a folder and the projects and boards in it.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the folder's company
Plan: Requires a plan that includes Portfolios (folders).
| folderId required | string <uuid> Example: f1a2b3c4-d5e6-4789-a012-3456789abcde Unique identifier of the folder (UUID) |
{- "id": "f1a2b3c4-d5e6-4789-a012-3456789abcde",
- "name": "Q1 2024 Projects",
- "company_id": 123456,
- "user_id": 123,
- "is_starred": true
}Renames or stars/unstars a folder. Starring is per-user and needs only company access; renaming needs edit access to the company.
Authentication required: Yes (Bearer token)
Validation: Name is at most 100 characters and unique within the company.
Plan: Requires a plan that includes Portfolios (folders).
| folderId required | string <uuid> Example: f1a2b3c4-d5e6-4789-a012-3456789abcde Unique identifier of the folder (UUID) |
| name | string [ 1 .. 100 ] characters New folder name (unique within the company) |
| is_starred | boolean Star or unstar the folder for the current user |
{- "name": "Q2 2024 Projects",
- "is_starred": true
}{- "id": "f1a2b3c4-d5e6-4789-a012-3456789abcde",
- "name": "Q1 2024 Projects",
- "company_id": 123456,
- "user_id": 123,
- "is_starred": true
}Deletes a folder. The projects and boards inside it are not deleted.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the company
Plan: Requires a plan that includes Portfolios (folders).
| folderId required | string <uuid> Example: f1a2b3c4-d5e6-4789-a012-3456789abcde Unique identifier of the folder (UUID) |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Lists the projects and boards in a folder, limited to those the current user can access.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the folder's company
Plan: Requires a plan that includes Portfolios (folders).
| folderId required | string <uuid> Example: f1a2b3c4-d5e6-4789-a012-3456789abcde Unique identifier of the folder (UUID) |
[- {
- "id": 920883,
- "name": "Website Redesign",
- "type": "project"
}
]Adds a project or board to a folder.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the company
Validation: The item must exist and must not already be in the folder.
Plan: Requires a plan that includes Portfolios (folders).
| folderId required | string <uuid> Example: f1a2b3c4-d5e6-4789-a012-3456789abcde Unique identifier of the folder (UUID) |
required | integer or string ID of the project (integer) or board (UUID) to add |
One of integer ID of the project (integer) or board (UUID) to add | |
| type required | string Enum: "project" "board" |
{- "id": 920883,
- "type": "project"
}{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Removes a project or board from a folder. The item itself is not deleted.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the company
Type: The type (project or board) is required because project and board IDs can overlap. Send it as a query parameter or in a JSON body.
Plan: Requires a plan that includes Portfolios (folders).
| folderId required | string <uuid> Example: f1a2b3c4-d5e6-4789-a012-3456789abcde Unique identifier of the folder (UUID) |
| itemId required | string Example: 920883 ID of the project or board to remove |
| type required | string Enum: "project" "board" Example: type=project Type of the item |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}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:
project_ids (array) to get costs for specific projectscompany_ids (array) to get costs for all projects within those companiesRequest Validation: project_ids and company_ids are optional, but if provided, must be arrays of IDs (for example project_ids[]=920883&project_ids[]=920884).
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).
| start_date required | string <date> Example: start_date=2024-01-01 Start date (YYYY-MM-DD) |
| end_date required | string <date> Example: end_date=2024-12-31 End date (YYYY-MM-DD) |
| project_ids | Array of integers Example: project_ids=920883 Only include these projects |
| company_ids | Array of integers Example: company_ids=123456 Include all projects in these companies |
[- {
- "type": "project",
- "type_id": 920883,
- "data": [
- {
- "month": "2024-01",
- "cost": 150000
}, - {
- "month": "2024-02",
- "cost": 175000
}
]
}, - {
- "type": "company",
- "type_id": 123456,
- "data": [
- {
- "month": "2024-01",
- "cost": 500000
}, - {
- "month": "2024-02",
- "cost": 525000
}
]
}
]Retrieves detailed information about the currently authenticated user.
Authentication required: Yes (Bearer token)
Response includes:
daily_project_summary_subscribed: Boolean, whether user is subscribed to daily project summary emailCompany 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.
{- "id": 12345,
- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "time_zone": "-05:00",
- "today_date": "2024-01-15",
- "status": "active",
- "daily_email_hour": 9,
- "companies": [
- {
- "id": 123456,
- "name": "Example Company"
}
], - "integrations": [ ],
- "preferences": { },
- "notifications": { },
- "mobile_notifications": { },
- "daily_project_summary_subscribed": true,
- "created_at": "2024-01-01T00:00:00Z"
}Updates the authenticated user's profile, notification settings or password. Send only the fields you want to change. Returns the full updated user, in the same shape as GET /current_user.
Authentication required: Yes (Bearer token)
Changing the password: Send current_password, password and password_confirm together. The new password must be at least 6 characters.
Changing the email: The new address must be valid and not already in use.
Errors: 400 with one of password_incorrect, password_mismatch, fails_password_policy, invalid_email, email_exists or malformed.
| first_name | string | ||
| last_name | string | ||
| email_address | string <email> | ||
| time_zone | string | ||
| daily_email_hour | integer Hour of the day (0-23) to send the daily email | ||
| daily_project_summary_subscribed | boolean Whether to receive the daily project summary email | ||
object Email notification settings, keyed by notification type | |||
| |||
object Mobile push notification settings, keyed by notification type | |||
| |||
| current_password | string <password> Required when changing the password | ||
| password | string <password> >= 6 characters New password | ||
| password_confirm | string <password> Must match | ||
{- "first_name": "Jane",
- "last_name": "Doe",
- "time_zone": "-05:00",
- "daily_project_summary_subscribed": true
}{- "id": 12345,
- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "time_zone": "-05:00",
- "today_date": "2024-01-15",
- "status": "active",
- "daily_email_hour": 9,
- "daily_project_summary_subscribed": true,
- "companies": [
- { }
], - "integrations": [
- { }
], - "integrationsNew": [
- { }
], - "preferencesNew": { },
- "preferences": { },
- "notifications": { },
- "mobile_notifications": { },
- "metrics": { },
- "welcome_survey": { },
- "created_at": "2024-01-01T00:00:00Z"
}Lists the current user's personal access tokens. The token secret is only shown when it's created, so it isn't included here.
Authentication required: Yes (Bearer token)
[- {
- "id": 123,
- "name": "Reporting script",
- "abilities": [
- "*"
], - "last_used_at": "2026-03-01T12:00:00Z",
- "created_at": "2026-02-01T12:34:56Z"
}
]Creates a personal access token for use as a Bearer token with the API.
Authentication required: Yes (Bearer token)
Important: The plain-text token is returned only in this response and can't be retrieved later. Store it securely.
| token_name required | string A label to help you recognize the token |
{- "token_name": "Reporting script"
}{- "token": "123|aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789"
}Revokes every personal access token the current user has created.
Authentication required: Yes (Bearer token)
Warning: Any scripts or integrations using these tokens stop working immediately. If you called this endpoint with a token, that token is revoked too.
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Revokes a single personal access token. Deleting a token ID that doesn't belong to the current user does nothing and still returns 204.
Authentication required: Yes (Bearer token)
| tokenId required | integer >= 1 Example: 123 Unique identifier of the personal access token |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Replaces the current user's profile picture. The image is resized to fit 400x400 and the previous picture is removed.
Authentication required: Yes (Bearer token)
Allowed formats: jpeg, jpg, gif, png. Other formats return 400 with extension_not_allowed; unreadable images return 400 with malformed_image.
| file required | string <binary> Image file (jpeg, jpg, gif or png) |
{
}Removes the current user from a company by disabling their membership. Their data in the company is kept, and an administrator can re-enable them.
Authentication required: Yes (Bearer token)
Permissions: User must be a member of the company.
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Creates or updates a single named preference for the current user. Use this for app settings that should follow the user across devices.
Authentication required: Yes (Bearer token)
Value: For boolean, number and string types send value. For json, send value_json and omit value.
Key format: At least 3 characters; letters, numbers and . - _ : only.
Special key: The notification primary method preference only accepts the supported method values.
| key required | string >= 3 characters ^[a-zA-Z0-9.\-_:]*$ | ||
| type required | string Enum: "boolean" "number" "string" "json" | ||
| value | any The value, for boolean, number and string types | ||
object The value, for the json type | |||
| |||
{- "key": "gantt.zoom",
- "type": "string",
- "value": "week"
}{- "key": "gantt.zoom",
- "type": "string",
- "value": "week",
- "value_json": { }
}Deletes one of the current user's preferences by key. Deleting a key that doesn't exist still returns 204.
Authentication required: Yes (Bearer token)
| key required | string Example: key=gantt.zoom Key of the preference to delete (may also be sent in a JSON body) |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Re-saves the current user's preferences to the newer preference store. This exists for client migration and is safe to call repeatedly.
Authentication required: Yes (Bearer token)
{- "updated": true
}Merges values into a named preference group (for example gantt or notifications). Send a JSON object of keys to set; a key set to null is removed from the group.
Authentication required: Yes (Bearer token)
Returns every preference group for the user.
| preference required | string Example: gantt Name of the preference group |
| property name* additional property | any |
{- "zoom": "week",
- "show_weekends": false,
- "old_setting": null
}{ }Returns the current user's onboarding checklist items and whether each is complete.
Authentication required: Yes (Bearer token)
[- {
- "key": "create_first_project",
- "is_complete": false
}
]Marks a checklist item complete or incomplete. Returns the full checklist.
Authentication required: Yes (Bearer token)
Returns 400 malformed if the key doesn't match a checklist item.
| key required | string Example: create_first_project Key of the checklist item |
| is_complete | boolean Default: false |
{- "is_complete": true
}[- {
- "key": "create_first_project",
- "is_complete": false
}
]Registers a device token so the user can receive push notifications on it.
Authentication required: Yes (Bearer token)
Returns 400 if the device is already registered or the body is malformed.
| token required | string Push notification token for the device |
| os required | string Device operating system |
{- "token": "abc123devicetoken",
- "os": "ios"
}{- "id": 55,
- "user_id": 123,
- "token": "abc123devicetoken",
- "os": "ios"
}Removes a registered device so it stops receiving push notifications. Unknown tokens still return 204.
Authentication required: Yes (Bearer token)
| token required | string Example: abc123devicetoken The device token that was registered |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Lists the registered API consumers (client applications) known to TeamGantt.
Authentication required: Yes (Bearer token)
Note: The list is not filtered to the current user.
[- {
- "id": 1,
- "name": "Mobile app"
}
]Lists the custom field definitions for a company.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the company
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
[- {
- "id": 9001,
- "company_id": 123456,
- "name": "Priority",
- "type": "select",
- "description": "How urgent the task is",
- "options": [
- "Low",
- "Medium",
- "High"
], - "default_enabled": true,
- "created_at": "2026-02-01T12:34:56Z"
}
]Creates a custom field definition. Once created, the field can be enabled per project and given values on tasks.
Authentication required: Yes (Bearer token)
Permissions: User must be able to edit the company
Types: boolean, text, date, number or select. Only select fields use options.
Default enablement: With default_enabled: true (the default), the field is available on every project unless it's turned off for that project.
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| name required | string |
| type required | string Enum: "boolean" "text" "date" "number" "select" |
| description | string or null |
| options | Array of strings or null Allowed values (for |
| default_enabled | boolean Default: true |
{- "name": "Priority",
- "type": "select",
- "description": "How urgent the task is",
- "options": [
- "Low",
- "Medium",
- "High"
]
}{- "id": 9001,
- "company_id": 123456,
- "name": "Priority",
- "type": "select",
- "description": "How urgent the task is",
- "options": [
- "Low",
- "Medium",
- "High"
], - "default_enabled": true
}Updates a custom field definition. All fields are optional.
Authentication required: Yes (Bearer token)
Permissions: User must be able to edit the company
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| customFieldId required | integer >= 1 Example: 9001 Unique identifier of the custom field |
| name | string |
| type | string Enum: "boolean" "text" "date" "number" "select" |
| description | string or null |
| options | Array of strings or null |
| default_enabled | boolean |
{- "name": "Urgency",
- "options": [
- "Low",
- "Medium",
- "High",
- "Critical"
]
}{- "id": 9001,
- "company_id": 123456,
- "name": "Priority",
- "type": "select",
- "description": "How urgent the task is",
- "options": [
- "Low",
- "Medium",
- "High"
], - "default_enabled": true
}Deletes a custom field definition.
Authentication required: Yes (Bearer token)
Permissions: User must be able to edit the company
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| customFieldId required | integer >= 1 Example: 9001 Unique identifier of the custom field |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Lists which custom fields are enabled or disabled on a project.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the company
Implied entries: Fields that use the company default and already have values on the project's tasks are included as enabled: true, even if no explicit setting has been saved.
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
[- {
- "project_id": 920883,
- "custom_field_id": 9001,
- "enabled": true
}
]Creates or updates the project-level setting for one custom field.
Authentication required: Yes (Bearer token)
Permissions: User must be able to edit the company
The field must belong to the company.
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| custom_field_id required | integer A custom field belonging to the company |
| enabled required | boolean |
{- "custom_field_id": 9001,
- "enabled": true
}{- "project_id": 920883,
- "custom_field_id": 9001,
- "enabled": true
}Removes a custom field value from a task, resetting it to empty.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the task
| customFieldValueId required | integer >= 1 Example: 12345 Unique identifier of the custom field value |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Retrieves all custom field values associated with a specific target (e.g., task).
Authentication required: Yes (Bearer token)
Permissions: User must have view access to the target resource
| targetType required | string Value: "task" Example: task The type of resource the custom field value is associated with |
| targetId required | integer >= 1 Example: 12345 Unique identifier of the target resource (task, group, or project) |
[- {
- "id": 12345,
- "custom_field_id": 9001,
- "target_type": "task",
- "target_id": 23456789,
- "value": "High",
- "updated_at": "2026-02-01T12:34:56Z",
- "updated_by": 674738
}
]Creates or updates a custom field value for a specific target and custom field.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the target resource
| targetType required | string Value: "task" Example: task The type of resource the custom field value is associated with |
| targetId required | integer >= 1 Example: 12345 Unique identifier of the target resource (task, group, or project) |
| customFieldId required | integer >= 1 Example: 9001 Unique identifier of the custom field |
| value | string The value to set for the custom field |
{- "value": "High"
}{- "id": 12345,
- "custom_field_id": 9001,
- "target_type": "task",
- "target_id": 23456789,
- "value": "High",
- "updated_at": "2026-02-01T12:34:56Z",
- "updated_by": 674738
}Marks all unread comments as read for the current user across every project they belong to.
Authentication required: Yes (Bearer token)
This processes comments in batches, so it can take a while on accounts with a lot of unread activity.
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Returns discussion metadata for a task, group or project: comment previews, unread status, mentions and commenters. This is the summary view; use the comments endpoint for full comment content.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the target resource
target is tasks, groups or projects.
For groups and projects, discussions are limited to comments on that resource itself.
| 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) |
{- "unread_count": 5,
- "unread_mention_count": 2,
- "discussions": [
- {
- "target_id": 23456789,
- "target": "task",
- "target_name": "Design homepage mockup",
- "project_id": 920883,
- "project_name": "Website Redesign",
- "last_comment_date": "2024-01-15T14:30:00Z",
- "message_preview": "Can we update the color scheme to match...",
- "commenters": [
- { }
], - "is_unread": true,
- "is_mentioned": true,
- "has_unread_mention": true,
- "is_my_task": true,
- "is_starred": false,
- "is_note": false,
- "has_documents": true
}
]
}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 commentsis_mentioned: Only discussions where the current user is mentionedhas_unread_mention: Only discussions with unread mentions of current useris_my_task: Only discussions for tasks assigned to current useris_starred: Only discussions for starred resourcesproject_id[]: Filter by specific project IDsoffset: 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).
| 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. |
{- "unread_count": 5,
- "unread_mention_count": 2,
- "discussions": [
- {
- "target_id": 23456789,
- "target": "task",
- "target_name": "Design homepage mockup",
- "project_id": 920883,
- "project_name": "Website Redesign",
- "last_comment_date": "2024-01-15T14:30:00Z",
- "message_preview": "Can we update the color scheme to match...",
- "is_unread": true,
- "is_mentioned": false,
- "has_unread_mention": false,
- "is_my_task": true,
- "is_starred": false,
- "is_note": false,
- "has_documents": true,
- "commenters": [ ]
}
]
}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.
| project_ids[] | Array of integers Example: project_ids[]=920883&project_ids[]=920884 Array of project IDs to filter documents. Can be specified multiple times. |
[- {
- "id": 67890,
- "name": "project-spec.pdf",
- "filename": "project-spec.pdf",
- "size": 2048576,
- "mime_type": "application/pdf",
- "created_at": "2024-01-15T10:30:00Z",
- "version": 1,
- "user_id": 123
}
]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
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| documentId required | integer >= 1 Example: 67890 Unique identifier of the document |
| q | string [ 1 .. 255 ] characters Example: q=meeting notes Optional search/filter query string |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}Reverts a task or group to the state recorded by a history entry, or recreates it if the entry records a deletion.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the project
Behavior:
restore_others controls whether related changes recorded alongside a task change are restored too. Omit it to use the default.Errors: 422 if the entry doesn't match the item, the item isn't deleted (for delete entries), or the action can't be restored. Only tasks (including milestones) and groups are supported.
The response describes what was restored.
| target required | string Enum: "tasks" "groups" Example: tasks Type of resource |
| id required | integer >= 1 Example: 23456789 ID of the task or group |
| logId required | integer >= 1 Example: 99999 ID of the history entry to restore |
| restore_others | boolean or null Also restore related changes recorded alongside a task change. Omit to use the default. |
{- "restore_others": false
}{ }Lists changes made to the project itself, newest first.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the project
For a feed that also includes groups and tasks, use the project activity endpoint.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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 |
[- {
- "id": 99999,
- "target": "task",
- "target_id": 23456789,
- "project_id": 920883,
- "key": "name",
- "value": "Design homepage mockup - v2",
- "user_id": 123,
- "user_name": "John Doe",
- "timestamp": "2024-01-15T14:30:00Z"
}
]Returns a combined activity feed for a project, covering changes to the project, its groups and its tasks, newest first.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the project
Pagination: Pass the next_cursor from the previous page as cursor for stable paging. offset is a legacy alternative and is ignored when cursor is given.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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 |
| cursor | string Opaque cursor from a previous response |
{- "items": [ ],
- "has_more": false,
- "next_cursor": null
}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:
parent_group_id to null or omit itparent_group_id to an existing group IDSort 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.
| 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) |
{- "project_id": 234567,
- "name": "My First Group",
- "parent_group_id": null,
- "sort": 1,
- "is_collapsed": false
}{- "id": 456789,
- "name": "My First Group",
- "project_id": 234567,
- "parent_group_id": null,
- "sort": 1,
- "is_collapsed": false,
- "children": [ ]
}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 namesort: Update sort orderis_collapsed: Update collapsed state (user-specific)required | Array of objects Array of group updates | ||||||||||
Array
| |||||||||||
{- "data": [
- {
- "id": 9969981,
- "parent_group_id": null,
- "name": "Updated Group Name",
- "sort": 2,
- "is_collapsed": false
}
]
}[- {
- "id": 9969981,
- "name": "Updated Group Name",
- "project_id": 234567,
- "parent_group_id": null,
- "sort": 2,
- "is_collapsed": false
}
]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.
| 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 |
[- {
- "id": 456789,
- "name": "Design Phase",
- "project_id": 234567,
- "parent_group_id": null,
- "sort": 1,
- "is_collapsed": false,
- "children": [
- {
- "id": 23456789,
- "name": "Design homepage mockup",
- "project_id": 234567,
- "parent_group_id": 456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-20"
}
]
}
]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.
| groupId required | integer >= 1 Example: 12345 Unique identifier of the group |
| flatten_children | boolean Example: flatten_children=true Whether to flatten nested groups into a flat list structure |
{- "id": 456789,
- "name": "Design Phase",
- "project_id": 234567,
- "parent_group_id": null,
- "sort": 1,
- "is_collapsed": false,
- "children": [
- {
- "id": 23456789,
- "name": "Design homepage mockup",
- "project_id": 234567,
- "parent_group_id": 456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-20"
}
]
}Updates a group's properties. Supports partial updates - only include the fields you want to change.
Authentication required: Yes (Bearer token)
Permissions:
project_id, parent_group_id, name, sort, and is_collapsedis_collapsed (user-specific collapsed state)Moving Groups:
project_id moves the group to a different project (requires edit permission on both projects)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.
| groupId required | integer >= 1 Example: 12345 Unique identifier of the group |
| 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 |
{- "name": "Updated Group Name",
- "sort": 2
}{- "id": 456789,
- "name": "Updated Group Name",
- "project_id": 234567,
- "parent_group_id": null,
- "sort": 2,
- "is_collapsed": false
}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.
| groupId required | integer >= 1 Example: 12345 Unique identifier of the group |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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:
is_flat_list=true: Returns a flat list of all descendant tasks and groupsResponse: Returns an array of tasks and groups. Each group may contain its own children unless is_flat_list=true is specified.
| groupId required | integer >= 1 Example: 12345 Unique identifier of the group |
| is_flat_list | boolean Example: is_flat_list=true Return children as a flat list instead of nested structure |
[- {
- "id": 23456789,
- "name": "Design homepage mockup",
- "project_id": 234567,
- "parent_group_id": 456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-20",
- "type": "task"
}, - {
- "id": 456790,
- "name": "Subgroup",
- "project_id": 234567,
- "parent_group_id": 456789,
- "children": [ ]
}
]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:
What Doesn't Get Copied:
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).
| groupId required | integer >= 1 Example: 12345 Unique identifier of the group |
| flatten_children | boolean Example: flatten_children=true Whether to flatten nested groups into a flat list structure |
{- "id": 456791,
- "name": "Design Phase",
- "project_id": 234567,
- "parent_group_id": null,
- "sort": 2,
- "is_collapsed": false,
- "children": [
- {
- "id": 23456790,
- "name": "Design homepage mockup",
- "project_id": 234567,
- "parent_group_id": 456791,
- "start_date": "2024-01-15",
- "end_date": "2024-01-20"
}
]
}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:
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.
| groupId required | integer >= 1 Example: 12345 Unique identifier of the group |
| 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 |
[- {
- "id": 99999,
- "target": "group",
- "target_id": 456789,
- "project_id": 234567,
- "key": "name",
- "value": "Updated Group Name",
- "user_id": 123,
- "user_name": "John Doe",
- "timestamp": "2024-01-15T14:30:00Z"
}
]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 relationshipremove: Remove items from a relationshipResource 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 relationshipdata: 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.
required | Array of objects (Operation) Array of operations to perform | ||||||
Array
| |||||||
{- "operations": [
- {
- "op": "add",
- "ref": {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "type": "columns",
- "relationship": "cards"
}, - "data": [
- {
- "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
}
]
}, - {
- "op": "remove",
- "ref": {
- "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "type": "columns",
- "relationship": "cards"
}, - "data": [
- {
- "id": "d4e5f6a7-b8c9-0123-def4-456789012345"
}
]
}
]
}{- "results": [
- {
- "success": true,
- "data": {
- "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
}
}, - {
- "success": true,
- "data": { }
}
]
}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.
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
{- "id": "abc123-def456-ghi789",
- "company_id": 123456,
- "lead_days": 30,
- "hidden_project_ids": [
- 123,
- 456,
- 789
], - "columns": [
- {
- "id": "col-abc-123",
- "board_id": "abc123-def456-ghi789",
- "name": "To Order",
- "sort": 1,
- "cards": [
- {
- "id": "card-123-def456",
- "board_id": "abc123-def456-ghi789",
- "column_id": "col-abc-123",
- "material_id": "mat-123-456",
- "sort": 5,
- "material": { },
- "task": { }
}
]
}
]
}Creates a new procurement board for a company.
Authentication required: Yes (Bearer token)
Permissions: User must have manage permissions on the company
Limitations:
Response: Returns the newly created procurement board.
Note: Cards are automatically synced based on hidden_project_ids after board creation. All other active company projects will be visible by default.
| company_id required | integer ID of the company |
| lead_days required | integer >= 1 Number of lead days for procurement planning |
| hidden_project_ids | Array of integers Array of project IDs to hide from the board (optional; defaults to empty array) |
{- "company_id": 123456,
- "lead_days": 30,
- "hidden_project_ids": [
- 123,
- 456,
- 789
]
}{- "id": "abc123-def456-ghi789",
- "company_id": 123456,
- "lead_days": 30,
- "hidden_project_ids": [
- 123,
- 456,
- 789
], - "columns": [
- {
- "id": "col-abc-123",
- "board_id": "abc123-def456-ghi789",
- "name": "To Order",
- "sort": 1,
- "cards": [
- {
- "id": "card-123-def456",
- "board_id": "abc123-def456-ghi789",
- "column_id": "col-abc-123",
- "material_id": "mat-123-456",
- "sort": 5,
- "material": { },
- "task": { }
}
]
}
]
}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.
| procurementBoardId required | string Example: abc123-def456-ghi789 Unique identifier of the procurement board |
{- "id": "abc123-def456-ghi789",
- "company_id": 123456,
- "lead_days": 30,
- "hidden_project_ids": [
- 123,
- 456,
- 789
], - "columns": [
- {
- "id": "col-abc-123",
- "board_id": "abc123-def456-ghi789",
- "name": "To Order",
- "sort": 1,
- "cards": [
- {
- "id": "card-123-def456",
- "board_id": "abc123-def456-ghi789",
- "column_id": "col-abc-123",
- "material_id": "mat-123-456",
- "sort": 5,
- "material": { },
- "task": { }
}
]
}
]
}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 planninghidden_project_ids: Array of project IDs to hide from the board (optional; replaces all hidden projects)Note: When updating hidden_project_ids, the existing hidden project list is replaced. Cards are automatically synced after update.
| procurementBoardId required | string Example: abc123-def456-ghi789 Unique identifier of the procurement board |
| lead_days | integer >= 1 Number of lead days for procurement planning |
| hidden_project_ids | Array of integers Array of project IDs to hide from the board (replaces existing) |
{- "lead_days": 30,
- "hidden_project_ids": [
- 123,
- 456,
- 789
]
}{- "id": "abc123-def456-ghi789",
- "company_id": 123456,
- "lead_days": 30,
- "hidden_project_ids": [
- 123,
- 456,
- 789
], - "columns": [
- {
- "id": "col-abc-123",
- "board_id": "abc123-def456-ghi789",
- "name": "To Order",
- "sort": 1,
- "cards": [
- {
- "id": "card-123-def456",
- "board_id": "abc123-def456-ghi789",
- "column_id": "col-abc-123",
- "material_id": "mat-123-456",
- "sort": 5,
- "material": { },
- "task": { }
}
]
}
]
}[DEPRECATED: Use '/procurement-boards/{procurementBoardId}/hidden-projects' instead.]
This endpoint is replaced by hidden-projects endpoints.
Old semantics added projects to the board; new boards display all active company projects not in hidden list. This endpoint is no longer supported.
| procurementBoardId required | string Example: abc123-def456-ghi789 Unique identifier of the procurement board |
{ }[DEPRECATED: Use '/procurement-boards/{procurementBoardId}/hidden-projects/{procurementBoardHiddenProjectId}' instead.]
This endpoint is replaced by hidden-projects endpoints.
| 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 |
[DEPRECATED: Use '/procurement-boards/{procurementBoardId}/hidden-projects/bulk-delete' instead.]
This endpoint is replaced by hidden-projects endpoints.
| procurementBoardId required | string Example: abc123-def456-ghi789 Unique identifier of the procurement board |
{ }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.
| procurementBoardId required | string Example: abc123-def456-ghi789 Unique identifier of the procurement board |
[- {
- "id": 12345,
- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "time_zone": "-05:00",
- "today_date": "2024-01-15",
- "status": "active",
- "daily_email_hour": 9,
- "daily_project_summary_subscribed": true,
- "companies": [
- { }
], - "integrations": [
- { }
], - "integrationsNew": [
- { }
], - "preferencesNew": { },
- "preferences": { },
- "notifications": { },
- "mobile_notifications": { },
- "metrics": { },
- "welcome_survey": { },
- "created_at": "2024-01-01T00:00:00Z"
}
]Adds a user to a procurement board.
Authentication required: Yes (Bearer token)
Permissions: User must have manage permissions on the company
Requirements:
Optional: Set send_invite: true to send an invitation email to the user.
| procurementBoardId required | string Example: abc123-def456-ghi789 Unique identifier of the procurement board |
| 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 |
{- "user_id": 123,
- "message": "You've been added to the procurement board",
- "send_invite": true
}{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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.
| procurementBoardId required | string Example: abc123-def456-ghi789 Unique identifier of the procurement board |
| userId required | integer >= 1 Example: 123 Unique identifier of the user |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}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.
| procurementBoardId required | string Example: abc123-def456-ghi789 Unique identifier of the procurement board |
| users required | Array of integers Array of user IDs to send invitations to |
| message | string Optional message to include in invitation email |
{- "users": [
- 123,
- 456
], - "message": "You've been invited to the procurement board"
}{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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.
| procurementBoardId required | string Example: abc123-def456-ghi789 Unique identifier of the procurement board |
[- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
]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:
Optional: Set send_invite: true to send invitation emails to all team members.
| procurementBoardId required | string Example: abc123-def456-ghi789 Unique identifier of the procurement board |
| 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 |
{- "team_id": "team-abc-123",
- "message": "Your team has been added to the procurement board",
- "send_invite": true
}{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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.
| 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 |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}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 columnsort: Change the sort order of the cardResponse: Returns the updated procurement card with material and task information.
| procurementCardId required | string Example: card-123-def456 Unique identifier of the procurement card |
| column_id | string ID of the column to move the card to |
| sort required | integer Sort order position |
{- "column_id": "col-abc-123",
- "sort": 5
}{- "id": "card-123-def456",
- "board_id": "abc123-def456-ghi789",
- "column_id": "col-abc-123",
- "material_id": "mat-123-456",
- "sort": 5,
- "material": { },
- "task": { }
}Updates a user's access to a project, including their permission level and color.
Authentication required: Yes (Bearer token)
Permissions:
permission and colorcolor (not permission)Permission Restrictions:
Color: The color is used to visually distinguish the user in resource views and Gantt charts.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| accesseId required | integer >= 1 Example: 7070608 Unique identifier of the project access record |
| 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 |
{- "permission": "edit",
- "color": "green2"
}{- "id": 7070608,
- "project_id": 920883,
- "company_id": 1000,
- "user_id": 1960234,
- "permission": "edit",
- "status": "Accepted",
- "color": "green2",
- "user": {
- "id": 1960234,
- "first_name": "John",
- "last_name": "Doe"
}
}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:
Warning: This operation cannot be undone. The user will need to be re-invited to regain access.
Response: Returns 204 No Content on success.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| accesseId required | integer >= 1 Example: 7070608 Unique identifier of the project access record |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}This endpoint has two modes based on the join query parameter:
Mode 1: Invite User (default) - Invite a user to join the project
user_id in request bodysend_invite: false)Mode 2: Join Project - Current user joins a project they own but are not yet a member of
?join=true query parameterAuthentication required: Yes (Bearer token)
Permissions:
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| join | string or null Example: join=true Set to any truthy value to join the project instead of inviting a user |
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) |
{- "user_id": 1960234,
- "color": "blue2",
- "custom_message": "Join the party!",
- "send_invite": true
}{- "id": 7070608,
- "project_id": 920883,
- "company_id": 1000,
- "user_id": 1960234,
- "permission": "edit",
- "status": "Pending",
- "color": "blue2",
- "custom_message": "Join the party!",
- "user": {
- "id": 1960234,
- "first_name": "John",
- "last_name": "Doe"
}
}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 acceptedAccepted: User has accepted and has access to the project| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
[- {
- "id": 7070608,
- "project_id": 920883,
- "company_id": 1000,
- "user_id": 1960234,
- "permission": "edit",
- "status": "Accepted",
- "color": "blue2",
- "user": {
- "id": 1960234,
- "first_name": "John",
- "last_name": "Doe"
}
}, - {
- "id": 7070609,
- "project_id": 920883,
- "company_id": 1000,
- "user_id": 1960235,
- "permission": "view_only",
- "status": "Pending",
- "color": "green1",
- "user": {
- "id": 1960235,
- "first_name": "Jane",
- "last_name": "Smith"
}
}
]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:
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.
| 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 is deprecated and not used. This endpoint accepts no body.
{ }{- "id": 7070608,
- "project_id": 920883,
- "company_id": 1000,
- "user_id": 1960234,
- "permission": "edit",
- "status": "Pending",
- "color": "blue2",
- "user": {
- "id": 1960234,
- "first_name": "John",
- "last_name": "Doe"
}
}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.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
[- {
- "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,
- "columns": [
- {
- "id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "name": "In Progress",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "sort": 2,
- "auto_move_cards": true,
- "auto_set_task_progress": 50,
- "cards": [
- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "column_id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "target_type": "task",
- "target_id": 23456789,
- "sort": 1
}
]
}
], - "users": [
- {
- "id": 12345,
- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "time_zone": "-05:00",
- "today_date": "2024-01-15",
- "status": "active",
- "daily_email_hour": 9,
- "daily_project_summary_subscribed": true,
- "companies": [
- { }
], - "integrations": [
- { }
], - "integrationsNew": [
- { }
], - "preferencesNew": { },
- "preferences": { },
- "notifications": { },
- "mobile_notifications": { },
- "metrics": { },
- "welcome_survey": { },
- "created_at": "2024-01-01T00:00:00Z"
}
], - "teams": [
- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
]
}
]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:
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.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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)
| |||||||
{- "columns": [
- {
- "name": "To Do",
- "auto_move_cards": false,
- "auto_set_task_progress": null
}, - {
- "name": "In Progress",
- "auto_move_cards": true,
- "auto_set_task_progress": 50
}, - {
- "name": "Done",
- "auto_move_cards": true,
- "auto_set_task_progress": 100
}
]
}{- "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,
- "columns": [
- {
- "id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "name": "In Progress",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "sort": 2,
- "auto_move_cards": true,
- "auto_set_task_progress": 50,
- "cards": [
- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "column_id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "target_type": "task",
- "target_id": 23456789,
- "sort": 1
}
]
}
], - "users": [
- {
- "id": 12345,
- "email_address": "user@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "time_zone": "-05:00",
- "today_date": "2024-01-15",
- "status": "active",
- "daily_email_hour": 9,
- "daily_project_summary_subscribed": true,
- "companies": [
- { }
], - "integrations": [
- { }
], - "integrationsNew": [
- { }
], - "preferencesNew": { },
- "preferences": { },
- "notifications": { },
- "mobile_notifications": { },
- "metrics": { },
- "welcome_survey": { },
- "created_at": "2024-01-01T00:00:00Z"
}
], - "teams": [
- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
]
}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.
Public vs Private: When public_keys[] or share_key + project_ids[] are present (for public/guest access), users must have public key access to the project. Otherwise, only authenticated users with access to the project may call this endpoint.
Response: Returns an array of baseline objects with basic information (no task details). Use GET /baselines/{id} to get full baseline with tasks.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
[- {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "name": "2020-Q1",
- "created_at": "2024-01-15T10:30:00Z"
}, - {
- "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
- "project_id": 920883,
- "name": "2020-Q2",
- "created_at": "2024-04-01T10:30:00Z"
}
]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:
Response: Returns the newly created baseline (without task details). Use GET /baselines/{id} to retrieve the full baseline with tasks.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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) |
{- "name": "2020-Q1"
}{- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "name": "2020-Q1",
- "created_at": "2024-01-15T10:30:00Z"
}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:
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.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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) |
{- "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "permission": "admin",
- "message": "Welcome to the project!",
- "send_invite": true
}{- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "permission": "admin",
- "team": {
- "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "name": "Development Team",
- "company_id": 1000
}
}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:
Response: Returns an array of RACI role assignments showing which users have which roles for each task, group, or project.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
[- {
- "id": 12345,
- "project_id": 920883,
- "target_type": "task",
- "target_id": 23456789,
- "resource_type": "user",
- "resource_id": 123,
- "roles": "RA"
}, - {
- "id": 12346,
- "project_id": 920883,
- "target_type": "task",
- "target_id": 23456789,
- "resource_type": "user",
- "resource_id": 124,
- "roles": "C"
}
]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:
Validation:
target_type must be "task", "group", or "project"resource_type must be "user" (currently only users are supported)Response: Returns the created or updated RACI role assignment.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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. |
{- "project_id": 1000,
- "target_type": "task",
- "target_id": 12345,
- "resource_type": "user",
- "resource_id": 1000,
- "roles": [
- "R",
- "A"
]
}{- "id": 12345,
- "project_id": 1000,
- "target_type": "task",
- "target_id": 12345,
- "resource_type": "user",
- "resource_id": 1000,
- "roles": "RA"
}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:
Response: Returns an object with three arrays, one for each resource type.
Use Cases:
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
{- "user_resources": [
- {
- "id": 123,
- "first_name": "John",
- "last_name": "Doe",
- "color": "blue1"
}
], - "company_resources": [
- {
- "id": 2754313,
- "name": "Conference Room A",
- "company_id": 1000
}
], - "project_resources": [
- {
- "id": 12345,
- "name": "Project Laptop",
- "project_id": 920883,
- "color": "green1",
- "created_at": "2024-01-15T10:30:00Z"
}
]
}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:
Note: This endpoint is functionally identical to /projects/{projectId}/resource_options. Use that endpoint instead for consistency.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
{- "user_resources": [
- { }
], - "company_resources": [
- {
- "id": 5000,
- "company_id": 123456,
- "name": "Conference Room A",
- "created_at": "2024-01-10T09:00:00Z"
}
], - "project_resources": [
- {
- "id": 12345,
- "project_id": 920883,
- "name": "Conference Room A",
- "color": "blue1",
- "created_at": "2024-01-15T10:30:00Z"
}
]
}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.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
[- {
- "id": 12345,
- "project_id": 920883,
- "name": "Conference Room A",
- "color": "blue2",
- "created_at": "2024-01-15T10:30:00Z"
}
]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:
Response: Returns the newly created project resource.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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 |
{- "name": "Project Resource",
- "color": "green1"
}{- "id": 12345,
- "project_id": 920883,
- "name": "Project Resource",
- "color": "green1",
- "created_at": "2024-01-15T10:30:00Z"
}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
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
{- "id": 12345,
- "project_id": 920883,
- "name": "Conference Room A",
- "color": "blue1",
- "created_at": "2024-01-15T10:30:00Z"
}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
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| name required | string [ 1 .. 255 ] characters Updated name of the resource |
{- "name": "Updated Resource"
}{- "id": 12345,
- "project_id": 920883,
- "name": "Conference Room A",
- "color": "blue1",
- "created_at": "2024-01-15T10:30:00Z"
}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
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
[- {
- "id": 12345,
- "project_id": 920883,
- "company_resource_id": 2754313,
- "color": "blue1",
- "resource": {
- "id": 5000,
- "company_id": 123456,
- "name": "Conference Room A",
- "created_at": "2024-01-10T09:00:00Z"
}
}
]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.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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 |
{- "company_resource_id": 1,
- "color": "blue2"
}{- "id": 12345,
- "project_id": 920883,
- "company_resource_id": 2754313,
- "color": "blue1",
- "resource": {
- "id": 5000,
- "company_id": 123456,
- "name": "Conference Room A",
- "created_at": "2024-01-10T09:00:00Z"
}
}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
| 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) |
| 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 |
{- "company_resource_id": 1,
- "color": "blue2"
}{- "id": 12345,
- "project_id": 920883,
- "company_resource_id": 2754313,
- "color": "blue1",
- "resource": {
- "id": 5000,
- "company_id": 123456,
- "name": "Conference Room A",
- "created_at": "2024-01-10T09:00:00Z"
}
}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
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| companyId required | integer Example: 12345 ID of the company resource link |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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.
Response: Returns a paginated list of time block objects.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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) |
{- "timeblocks": [
- {
- "id": 78901,
- "task_id": 23456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-17",
- "hours": 24,
- "resource_id": 1000
}
], - "total": 120,
- "count": 50,
- "current_page": 1
}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:
Calculation: For each project, the endpoint:
Use Cases:
Response: Returns an array of health report objects, one for each requested project.
| ids[] | Array of integers Example: ids[]=920883&ids[]=920884 Array of project IDs to generate health reports for |
[- {
- "id": "920883",
- "task_status": {
- "on_schedule": 15,
- "overdue": 3,
- "behind": 2,
- "upcoming": 10
}, - "percent_complete": 62.5
}, - {
- "id": "920884",
- "task_status": {
- "on_schedule": 8,
- "overdue": 1,
- "behind": 0,
- "upcoming": 5
}, - "percent_complete": 75
}
]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 objectreport_data: Health metrics objectResource Filtering: The offset parameter can be used to apply resource filters (legacy behavior).
| 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) |
[- {
- "project": {
- "id": 920883,
- "name": "Website Redesign"
}, - "report_data": {
- "task_status": {
- "on_schedule": 15,
- "overdue": 3,
- "behind": 2,
- "upcoming": 10
}, - "percent_complete": 62.5
}
}
]Retrieves a paginated list of projects accessible to the current user.
Authentication required: Yes (Bearer token)
Default Filters:
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 companiesq: Search query to filter by project namefields[]: (Optional—NEW) Return only the specified fields for each project, e.g. fields[]=id&fields[]=name. Allowed: id, name, company_id, status, is_starred, permission, start_date, end_date, has_joined, current_access_id, members, admin_emails, accesses, teams.Response:
fields are specified: returns only those fields per project (no nested objects).Sorting:
| 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 |
| fields[] | Array of strings Items Enum: "id" "name" "company_id" "status" "is_starred" "permission" "start_date" "end_date" "has_joined" "current_access_id" "members" "admin_emails" "accesses" "teams" Example: fields[]=id&fields[]=name (Optional) List of project fields to include in response (sparse field selection—NEW). Omitting this returns full project objects. Allowed: |
{- "total": 25,
- "count": 25,
- "current_page": 1,
- "projects": [
- {
- "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": [
- 1,
- 2,
- 3,
- 4,
- 5
], - "public_key": null,
- "permission": "admin",
- "is_starred": false,
- "created_at": "2024-01-01T00:00:00Z",
- "accesses": [
- {
- "id": 7070608,
- "project_id": 920884,
- "company_id": 1000,
- "user_id": 1960234,
- "user": { },
- "permission": "edit",
- "status": "Accepted",
- "project_status": "active",
- "color": "blue1",
- "custom_message": "Join the party!"
}
], - "teams": [
- {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "permission": "admin",
- "team": {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
}
], - "company": { },
- "integrations": [
- { }
], - "metrics": { },
- "custom_fields": [
- {
- "id": 1001,
- "name": "PO Number",
- "type": "text",
- "options": [
- "A",
- "B"
], - "description": "Field for storing PO numbers"
}
]
}
]
}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:
template with a template project IDimport_* flags to control what gets copied (checklists, comments, notes)User Invitations:
accesses array with user IDs to inviteWorking Days:
chart_days: Array of working days (1=Monday, 7=Sunday)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.
| 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 |
{- "company_id": 1000,
- "name": "Sample Project",
- "chart_days": [
- 1,
- 2,
- 3,
- 4,
- 5
], - "default_view": "gantt"
}{- "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": [
- 1,
- 2,
- 3,
- 4,
- 5
], - "public_key": null,
- "permission": "admin",
- "is_starred": false,
- "created_at": "2024-01-01T00:00:00Z",
- "accesses": [
- {
- "id": 7070608,
- "project_id": 920884,
- "company_id": 1000,
- "user_id": 1960234,
- "user": { },
- "permission": "edit",
- "status": "Accepted",
- "project_status": "active",
- "color": "blue1",
- "custom_message": "Join the party!"
}
], - "teams": [
- {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "permission": "admin",
- "team": {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
}
], - "company": { },
- "integrations": [
- { }
], - "metrics": { },
- "custom_fields": [
- {
- "id": 1001,
- "name": "PO Number",
- "type": "text",
- "options": [
- "A",
- "B"
], - "description": "Field for storing PO numbers"
}
]
}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 companiesstatus: Filter by project statusfields[]: Specify which fields to include in the responseResponse: 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.
| 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 |
{- "total": 25,
- "count": 25,
- "current_page": 1,
- "projects": [
- {
- "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": [
- 1,
- 2,
- 3,
- 4,
- 5
], - "public_key": null,
- "permission": "admin",
- "is_starred": false,
- "created_at": "2024-01-01T00:00:00Z",
- "accesses": [
- {
- "id": 7070608,
- "project_id": 920884,
- "company_id": 1000,
- "user_id": 1960234,
- "user": { },
- "permission": "edit",
- "status": "Accepted",
- "project_status": "active",
- "color": "blue1",
- "custom_message": "Join the party!"
}
], - "teams": [
- {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "permission": "admin",
- "team": {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
}
], - "company": { },
- "integrations": [
- { }
], - "metrics": { },
- "custom_fields": [
- {
- "id": 1001,
- "name": "PO Number",
- "type": "text",
- "options": [
- "A",
- "B"
], - "description": "Field for storing PO numbers"
}
]
}
]
}Retrieves comprehensive information about a specific project.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the project
Response includes:
Use Cases:
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
{- "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": [
- 1,
- 2,
- 3,
- 4,
- 5
], - "public_key": null,
- "permission": "admin",
- "is_starred": false,
- "created_at": "2024-01-01T00:00:00Z",
- "accesses": [
- {
- "id": 7070608,
- "project_id": 920884,
- "company_id": 1000,
- "user_id": 1960234,
- "user": { },
- "permission": "edit",
- "status": "Accepted",
- "project_status": "active",
- "color": "blue1",
- "custom_message": "Join the party!"
}
], - "teams": [
- {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "permission": "admin",
- "team": {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
}
], - "company": { },
- "integrations": [
- { }
], - "metrics": { },
- "custom_fields": [
- {
- "id": 1001,
- "name": "PO Number",
- "type": "text",
- "options": [
- "A",
- "B"
], - "description": "Field for storing PO numbers"
}
]
}Updates project settings and configuration. Supports partial updates.
Authentication required: Yes (Bearer token)
Permissions:
is_starred onlyUpdateable Fields:
name: Project namestatus: Project status (active, on hold, complete)default_view: Default view modechart_days: Working days of the weekis_template: Template statushas_hours_enabled: Hour trackingin_resource_management: Resource management visibilityallow_scheduling_on_holidays: Holiday schedulinglock_milestone_dates: Milestone date lockingcalendar_start_date: Calendar start date overridepublic_key: Public access keyis_starred: Starred status (only requires access permission)Status Changes:
History: All changes are logged to the project history.
Response: Returns the updated project object with all nested relationships.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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 |
{- "status": "active"
}{- "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": [
- 1,
- 2,
- 3,
- 4,
- 5
], - "public_key": null,
- "permission": "admin",
- "is_starred": false,
- "created_at": "2024-01-01T00:00:00Z",
- "accesses": [
- {
- "id": 7070608,
- "project_id": 920884,
- "company_id": 1000,
- "user_id": 1960234,
- "user": { },
- "permission": "edit",
- "status": "Accepted",
- "project_status": "active",
- "color": "blue1",
- "custom_message": "Join the party!"
}
], - "teams": [
- {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "permission": "admin",
- "team": {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
}
], - "company": { },
- "integrations": [
- { }
], - "metrics": { },
- "custom_fields": [
- {
- "id": 1001,
- "name": "PO Number",
- "type": "text",
- "options": [
- "A",
- "B"
], - "description": "Field for storing PO numbers"
}
]
}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:
History: The status change is logged to the project history.
Response: Returns 204 No Content on success.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}Sorts groups and catalog entries (tasks, milestones, subgroups) in the project by their earliest start_date ascending. The sort will update database orderings so that tasks/groups appear in chronological order.
Authentication required: Yes (Bearer token)
Body:
sort_by: Required, must be array containing only "start_date" (currently only value supported)Permissions: User must have edit permission on the project.
Effects: The group and catalog sort_order within the project is updated based on earliest start_date.
Response:
sort_by is not supported| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| sort_by required | Array of strings Items Value: "start_date" Sorting keys; currently only ["start_date"] supported |
{- "sort_by": [
- "start_date"
]
}{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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:
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.
| ids[] required | Array of integers Example: ids[]=920883 Array of project IDs to export |
{- "id": 67890,
- "name": "project-export.csv",
- "created_at": "2024-01-15T10:30:00Z"
}Imports a new project from CSV data.
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.
Input: Provide the CSV contents as a raw string in csv_data.
| company_id required | integer ID of the company to import the project into |
| csv_data required | string Raw CSV data as a string (including header row if present) |
| has_hours_enabled | boolean Default: false Whether hour tracking should be enabled on the imported project |
{- "company_id": 1000,
- "has_hours_enabled": false,
- "csv_data": "WBS,Name,Type,Start Date,End Date,Color\n1,Website Redesign,Project,2024-01-01,2024-02-01,blue1\n1.1,Design,Group,,,green2\n1.1.1,Homepage mockups,Task,2024-01-02,2024-01-10,orange3\n"
}{- "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": [
- 1,
- 2,
- 3,
- 4,
- 5
], - "public_key": null,
- "permission": "admin",
- "is_starred": false,
- "created_at": "2024-01-01T00:00:00Z",
- "accesses": [
- {
- "id": 7070608,
- "project_id": 920884,
- "company_id": 1000,
- "user_id": 1960234,
- "user": { },
- "permission": "edit",
- "status": "Accepted",
- "project_status": "active",
- "color": "blue1",
- "custom_message": "Join the party!"
}
], - "teams": [
- {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "permission": "admin",
- "team": {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
}
], - "company": { },
- "integrations": [
- { }
], - "metrics": { },
- "custom_fields": [
- {
- "id": 1001,
- "name": "PO Number",
- "type": "text",
- "options": [
- "A",
- "B"
], - "description": "Field for storing PO numbers"
}
]
}Retrieves all groups and tasks for a project.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the project
Nested vs Flat:
is_flat_list=true: Returns a flat list of all groups and tasksNEW: If the current user does not have permission edit or admin on the company, cost information (task_cost) is omitted from each task in the response, regardless of company features.
Efficient loading: This endpoint is optimized for fast, consistent reads—nested objects are statically ordered and can be retrieved with a single call.
Response: Returns an array of groups and tasks. By default, the structure is hierarchical with root groups containing their children.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| is_flat_list | boolean Example: is_flat_list=true Return children as a flat list instead of nested structure |
[- {
- "id": 456789,
- "name": "Design Phase",
- "project_id": 920883,
- "parent_group_id": null,
- "sort": 1,
- "is_collapsed": false,
- "children": [
- {
- "id": 23456789,
- "name": "Design homepage mockup",
- "project_id": 920883,
- "parent_group_id": 456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-20"
}
]
}
]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 tasksTask 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.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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 |
{- "color": "blue1"
}[- {
- "id": 23456789,
- "name": "Design homepage mockup",
- "project_id": 920883,
- "parent_group_id": 456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-20",
- "duration": 5,
- "percent_complete": 50,
- "color": "blue1",
- "type": "task",
- "estimated_hours": 40,
- "estimate": "M",
- "sort": 1,
- "is_starred": false,
- "status": "in_progress",
- "priority": "high",
- "created_at": "2024-01-10T09:00:00Z",
- "created_by": 1000,
- "updated_at": "2024-01-15T14:30:00Z",
- "updated_by": 1000,
- "task_cost": {
- "cost": 50000,
- "cost_load_mode": "front"
}, - "custom_field_values": [
- {
- "custom_field_id": 1005,
- "value": "PO-12345"
}
]
}
]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.
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}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 targetbelow: Place children below the targetwithin: Place children as children of the targetTarget Types: Can be a task, group, or project
Response: Returns the updated project structure.
required | Array of objects Array of child items to move | ||||
Array
| |||||
required | object | ||||
| |||||
| intent required | string Enum: "above" "below" "within" Where to place the children relative to the target | ||||
{- "children": [
- {
- "type": "task",
- "id": 123
}, - {
- "type": "group",
- "id": 456
}
], - "target": {
- "type": "group",
- "id": 789
}, - "intent": "within"
}{ }Retrieves a baseline, including its task snapshots.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the project
| id required | string <uuid> Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 Unique identifier of the baseline (UUID) |
{- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "name": "2020-Q1",
- "created_at": "2024-01-15T10:30:00Z",
- "updated_at": "2024-01-15T10:30:00Z"
}Updates a baseline's name.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the project
| id required | string <uuid> Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 Unique identifier of the baseline (UUID) |
| name required | string [ 1 .. 255 ] characters Updated name for the baseline |
{- "name": "2020-Q1 Updated"
}{- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "name": "2020-Q1",
- "created_at": "2024-01-15T10:30:00Z",
- "updated_at": "2024-01-15T10:30:00Z"
}Deletes a baseline and its task snapshots.
Authentication required: Yes (Bearer token)
Permissions: User must have admin access to the project
| id required | string <uuid> Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 Unique identifier of the baseline (UUID) |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Lists the task snapshots saved in a baseline: each task's start date, end date and percent complete when the baseline was created.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the project. Public/shared views can instead authorize with share_key (or public_keys) plus project_ids.
| id required | string <uuid> Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 Unique identifier of the baseline (UUID) |
| share_key | string Share key for public access. Must be combined with |
| project_ids | Array of integers Project IDs the share key or public keys grant access to |
[- {
- "id": 501,
- "task_id": 23456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-20",
- "percent_complete": 50
}
]Updates the project-specific settings for a company resource, such as the color override.
Authentication required: Yes (Bearer token)
Permissions: User must have edit permissions on the project
Updates: Currently only the color can be updated. The company_resource_id must be provided but cannot be changed.
Response: Returns the updated project-company resource link.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| company_resource_optionId required | integer >= 1 Example: 12345 Unique identifier of the company resource option link |
| 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 |
{- "company_resource_id": 2754313,
- "color": "green2"
}{- "id": 12345,
- "project_id": 920883,
- "company_resource_id": 2754313,
- "color": "green2",
- "resource": {
- "id": 2754313,
- "name": "Conference Room A",
- "company_id": 1000
}
}Removes a company resource from a project. The resource will no longer be available for task assignments in this project.
Authentication required: Yes (Bearer token)
Permissions: User must have edit permissions on the project
Effects:
Response: Returns 204 No Content on success.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| company_resource_optionId required | integer >= 1 Example: 12345 Unique identifier of the company resource option link |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}Calculates and returns the critical path for a project - the sequence of tasks that determines the minimum project duration.
Authentication: Optional. Provide either:
share_key + project_ids[] query parameters for public/shared access.Permissions: Either the authenticated user must have access to the project, or the provided share_key must grant access to the projectId.
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:
Empty Response: If the project has no tasks, returns an empty array.
Use Cases:
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| share_key | string Example: share_key=abc123sharekey Share key used to authenticate public access (required when using |
| project_ids[] | Array of integers Example: project_ids[]=920883 Array of project IDs available to the share key (required when using |
[- {
- "id": 23456789,
- "name": "Design homepage mockup",
- "start_date": "2024-01-15",
- "end_date": "2024-01-20",
- "predecessors": [ ],
- "successors": [
- 23456790
], - "is_critical": true
}, - {
- "id": 23456790,
- "name": "Develop homepage",
- "start_date": "2024-01-21",
- "end_date": "2024-01-30",
- "predecessors": [
- 23456789
], - "successors": [ ],
- "is_critical": true
}
]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:
Calculation: For each board, the endpoint:
Response: Returns an array of health report objects, one for each requested board.
| ids[] | Array of strings <uuid> [ items <uuid > ] Example: ids[]=443c80e4-72dc-4363-afd8-b58e6d866b63 Array of board IDs (UUIDs) to generate health reports for |
[- {
- "id": "443c80e4-72dc-4363-afd8-b58e6d866b63",
- "task_status": {
- "on_schedule": 15,
- "overdue": 3,
- "behind": 2,
- "upcoming": 10
}, - "percent_complete": 62.5
}
]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:
Calculation: For each project, the endpoint:
Use Cases:
Response: Returns an array of health report objects, one for each requested project.
| ids[] | Array of integers Example: ids[]=920883&ids[]=920884 Array of project IDs to generate health reports for |
[- {
- "id": "920883",
- "task_status": {
- "on_schedule": 15,
- "overdue": 3,
- "behind": 2,
- "upcoming": 10
}, - "percent_complete": 62.5
}, - {
- "id": "920884",
- "task_status": {
- "on_schedule": 8,
- "overdue": 1,
- "behind": 0,
- "upcoming": 5
}, - "percent_complete": 75
}
]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 objectreport_data: Health metrics objectResource Filtering: The offset parameter can be used to apply resource filters (legacy behavior).
| 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) |
[- {
- "project": {
- "id": 920883,
- "name": "Website Redesign"
}, - "report_data": {
- "task_status": {
- "on_schedule": 15,
- "overdue": 3,
- "behind": 2,
- "upcoming": 10
}, - "percent_complete": 62.5
}
}
]Sends schedule confirmation notifications to users for specific tasks.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the tasks
Behavior:
Response: Returns 204 No Content on success.
required | Array of objects Array of user-task combinations to send confirmations for | ||||
Array
| |||||
{- "user_tasks": [
- {
- "user_id": 123,
- "task_ids": [
- 456,
- 789
]
}, - {
- "user_id": 124,
- "task_ids": [
- 789,
- 101
]
}
]
}{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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.
| scheduleConfirmationId required | integer >= 1 Example: 12345 Unique identifier of the schedule confirmation |
| status required | string Enum: "not_notified" "pending" "confirmed" "declined" New status for the confirmation |
{- "status": "confirmed"
}{- "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
}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:
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| include | string Example: include=board,board.columns Comma-separated list of relationships to include in the response |
{- "data": [
- {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "board_id": "0604a8a4-d4b4-48db-9106-9db0d1b11b73",
- "column_id": "544b6464-b8fd-489e-8ef0-651b855e6c13",
- "target_type": "task",
- "target_id": 23456789,
- "sort": 1
}, - {
- "id": "b2c3d4e5-f6a7-4890-b123-456789abcdef",
- "board_id": "1715b9b5-c5d7-4890-b123-4567890bcdef",
- "column_id": "655c7575-c9fe-49af-9f01-762c966d7d24",
- "target_type": "task",
- "target_id": 23456789,
- "sort": 3
}
]
}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:
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
[- {
- "id": 67890,
- "name": "project-spec.pdf",
- "filename": "project-spec.pdf",
- "size": 2048576,
- "mime_type": "application/pdf",
- "created_at": "2024-01-15T10:30:00Z",
- "version": 1,
- "user_id": 123
}
]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
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| parent | integer Example: parent=67890 ID of parent document (for adding a new version to existing document) |
Document file to upload
| file required | string <binary> The file to upload |
| description | string Optional description of the document |
{- "id": 67891,
- "name": "updated-spec.pdf",
- "filename": "updated-spec.pdf",
- "size": 3145728,
- "mime_type": "application/pdf",
- "created_at": "2024-01-17T10:30:00Z",
- "version": 2,
- "user_id": 123
}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:
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
{- "message": "All documents marked as read"
}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.
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| documentId required | integer >= 1 Example: 67890 Unique identifier of the document |
Updated document metadata
| name | string [ 1 .. 255 ] characters Updated name for the document |
| description | string <= 1000 characters Updated description |
{- "name": "Final Project Specifications v2"
}{- "id": 67890,
- "name": "project-spec.pdf",
- "filename": "project-spec.pdf",
- "size": 2048576,
- "mime_type": "application/pdf",
- "created_at": "2024-01-15T10:30:00Z",
- "version": 1,
- "user_id": 123
}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:
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| documentId required | integer >= 1 Example: 67890 Unique identifier of the document |
{- "message": "Document deleted successfully",
- "data": {
- "id": 67890
}
}Retrieves the complete audit log of all changes made to a task.
History entries track every modification including:
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:
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| 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 |
[- {
- "id": 99999,
- "target": "task",
- "target_id": 23456789,
- "project_id": 920883,
- "key": "name",
- "value": "Design homepage mockup - v2",
- "user_id": 123,
- "user_name": "John Doe",
- "timestamp": "2024-01-15T14:30:00Z"
}, - {
- "id": 99998,
- "target": "task",
- "target_id": 23456789,
- "project_id": 920883,
- "key": "percent complete",
- "value": "50",
- "user_id": 123,
- "user_name": "John Doe",
- "timestamp": "2024-01-15T14:00:00Z"
}, - {
- "id": 99997,
- "target": "task",
- "target_id": 23456789,
- "project_id": 920883,
- "key": "dates",
- "value": "2024-01-15:2024-01-20",
- "user_id": 124,
- "user_name": "Jane Smith",
- "timestamp": "2024-01-12T10:15:00Z"
}
]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 tasksTask 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.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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 |
{- "color": "blue1"
}[- {
- "id": 23456789,
- "name": "Design homepage mockup",
- "project_id": 920883,
- "parent_group_id": 456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-20",
- "duration": 5,
- "percent_complete": 50,
- "color": "blue1",
- "type": "task",
- "estimated_hours": 40,
- "estimate": "M",
- "sort": 1,
- "is_starred": false,
- "status": "in_progress",
- "priority": "high",
- "created_at": "2024-01-10T09:00:00Z",
- "created_by": 1000,
- "updated_at": "2024-01-15T14:30:00Z",
- "updated_by": 1000,
- "task_cost": {
- "cost": 50000,
- "cost_load_mode": "front"
}, - "custom_field_values": [
- {
- "custom_field_id": 1005,
- "value": "PO-12345"
}
]
}
]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:
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
[- {
- "id": 54321,
- "target_id": 23456789,
- "project_id": 920883,
- "name": "Review design mockups",
- "is_complete": true,
- "sort": 1,
- "added_date": "2024-01-10T09:00:00Z"
}, - {
- "id": 54322,
- "target_id": 23456789,
- "project_id": 920883,
- "name": "Get client feedback",
- "is_complete": false,
- "sort": 2,
- "added_date": "2024-01-10T09:05:00Z"
}, - {
- "id": 54323,
- "target_id": 23456789,
- "project_id": 920883,
- "name": "Finalize design",
- "is_complete": false,
- "sort": 3,
- "added_date": "2024-01-10T09:10:00Z"
}
]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.
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
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 |
{- "name": "Review design mockups"
}{- "id": 54324,
- "target_id": 23456789,
- "project_id": 920883,
- "name": "Review design mockups",
- "is_complete": false,
- "sort": 4,
- "added_date": "2024-01-17T10:30:00Z"
}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:
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| checklist_itemId required | integer >= 1 Example: 54321 Unique identifier of the checklist item |
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 |
{- "is_complete": true
}{- "id": 54321,
- "target_id": 23456789,
- "project_id": 920883,
- "name": "Review and approve final design mockups",
- "is_complete": true,
- "sort": 1,
- "added_date": "2024-01-10T09:00:00Z"
}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.
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| checklist_itemId required | integer >= 1 Example: 54321 Unique identifier of the checklist item |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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:
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| type | string Enum: "user" "team" "company_resource" Example: type=user Filter resources by type |
[- {
- "id": 123456,
- "task_id": 23456789,
- "project_id": 920883,
- "type": "user",
- "type_id": 1000,
- "name": "John Doe",
- "color": "blue1",
- "schedule_confirmation": {
- "id": null,
- "status": "not_notified"
}, - "hours_per_day": 8,
- "total_hours": 40
}, - {
- "id": 123457,
- "task_id": 23456789,
- "project_id": 920883,
- "type": "team",
- "type_id": 2000,
- "name": "Development Team",
- "color": "green2",
- "hours_per_day": 6,
- "total_hours": 30
}
]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.
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
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) |
{- "type": "user",
- "type_id": 1000,
- "hours_per_day": 8,
- "total_hours": 40
}{- "id": 123458,
- "task_id": 23456789,
- "project_id": 920883,
- "type": "user",
- "type_id": 1000,
- "name": "John Doe",
- "color": "blue1",
- "hours_per_day": 8,
- "total_hours": 40
}Assigns every eligible user in a team to the specified task.
Authentication required: Yes (Bearer token)
Permissions: User must have write access to the project containing the task.
Eligibility rules:
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| team_id required | string <uuid> Team ID whose users should be assigned to the task |
| hours_per_day | number or null Hours per day to assign for each user (optional) |
| total_hours | number or null Total hours to assign for each user (optional) |
{- "team_id": "2dd9f6b0-0b0a-4bb3-9a4e-8ed0c2b65b11",
- "hours_per_day": 8,
- "total_hours": 40
}{- "team_id": "2dd9f6b0-0b0a-4bb3-9a4e-8ed0c2b65b11",
- "resources": [
- {
- "id": 123456,
- "task_id": 23456789,
- "project_id": 920883,
- "type": "user",
- "type_id": 1000,
- "name": "John Doe",
- "color": "blue1",
- "hours_per_day": 8,
- "total_hours": 40
}
]
}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.
| 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 |
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) |
{- "hours_per_day": 5,
- "total_hours": 25
}{- "id": 123456,
- "task_id": 23456789,
- "project_id": 920883,
- "type": "user",
- "type_id": 1000,
- "name": "John Doe",
- "color": "blue1",
- "schedule_confirmation": {
- "id": 555,
- "status": "pending"
}, - "hours_per_day": 5,
- "total_hours": 25
}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.
| 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 |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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:
Lead/Lag Time:
Validation:
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
Dependency relationship data
required | object The task to create a dependency to (the predecessor) | ||
| |||
| 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) | ||
{- "to_task": {
- "id": 34567890
}, - "type": "FS",
- "lead_lag_time": 0
}{- "id": 12345,
- "project_id": 920883,
- "from_task": {
- "id": 23456789,
- "name": "Design homepage mockup",
- "users": [ ],
- "color": "blue2",
- "type": "task",
- "percent_complete": 0
}, - "to_task": {
- "id": 34567890,
- "name": "Build homepage",
- "users": [ ],
- "color": "blue2",
- "type": "task",
- "percent_complete": 0
}, - "lead_lag_time": 0,
- "type": "FS"
}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:
Note: This does not delete the tasks themselves, only the dependency between them.
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| dependencieId required | integer >= 1 Example: 12345 Unique identifier of the dependency to delete |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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:
fields[] query parameter. If present, only the requested properties will be included for each task. Allowed: id, project_id, project_name, project_permission, project_is_starred, parent_group_id, parent_group_name, company_id, sort, name, start_date, end_date, percent_complete, type, color, is_time_tracking_enabled, resources, wbs.selection=global_time_tracker to fetch the list of tasks used by the shell global time tracker widget, together with sparse field selection (mutually exclusive with other filters).| 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 |
| fields[] | Array of strings Example: fields[]=id&fields[]=project_id&fields[]=name&fields[]=start_date (Optional—NEW) When provided, return only the selected fields for each task (sparse fieldset). Allowed values: |
| selection | string Value: "global_time_tracker" Example: selection=global_time_tracker (Optional—NEW) Specify a well-known server-side task selection for the shell, e.g. |
[- {
- "id": 23456789,
- "name": "Design homepage mockup",
- "project_id": 920883,
- "parent_group_id": 456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-20",
- "duration": 5,
- "percent_complete": 50,
- "status": "in_progress",
- "priority": "high",
- "created_at": "2024-01-10T09:00:00Z",
- "updated_at": "2024-01-15T14:30:00Z"
}, - {
- "id": 23456790,
- "name": "Implement API endpoints",
- "project_id": 920883,
- "parent_group_id": 456789,
- "start_date": "2024-01-16",
- "end_date": "2024-01-25",
- "duration": 8,
- "percent_complete": 25,
- "status": "in_progress",
- "priority": "medium",
- "created_at": "2024-01-10T09:15:00Z",
- "updated_at": "2024-01-16T10:00:00Z"
}
]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
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 | |||||
| |||||
{- "project_id": 920883,
- "parent_group_id": 456789,
- "name": "New task created via API"
}{- "id": 23456791,
- "name": "New task created via API",
- "project_id": 920883,
- "parent_group_id": 456789,
- "start_date": "2024-01-17",
- "end_date": "2024-01-17",
- "duration": 1,
- "percent_complete": 0,
- "status": "not_started",
- "created_at": "2024-01-17T10:30:00Z",
- "updated_at": "2024-01-17T10:30:00Z"
}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:
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": 920883,
- "tasks": [
- {
- "project_id": 920883,
- "parent_group_id": 7272598,
- "name": "Task 1 - Requirements gathering",
- "start_date": "2024-01-15",
- "end_date": "2024-01-18"
}, - {
- "project_id": 920883,
- "parent_group_id": 7272598,
- "name": "Task 2 - Design mockups",
- "start_date": "2024-01-19",
- "end_date": "2024-01-25"
}, - {
- "project_id": 920883,
- "parent_group_id": 7272599,
- "name": "Task 3 - Implementation",
- "start_date": "2024-01-26",
- "end_date": "2024-02-05"
}
]
}{- "tasks": [
- {
- "id": 23456791,
- "name": "Task 1 - Requirements gathering",
- "project_id": 920883,
- "parent_group_id": 7272598,
- "start_date": "2024-01-15",
- "end_date": "2024-01-18"
}, - {
- "id": 23456792,
- "name": "Task 2 - Design mockups",
- "project_id": 920883,
- "parent_group_id": 7272598,
- "start_date": "2024-01-19",
- "end_date": "2024-01-25"
}
]
}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
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
{- "id": 23456789,
- "name": "Design homepage mockup",
- "project_id": 920883,
- "parent_group_id": 456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-20",
- "duration": 5,
- "percent_complete": 50,
- "status": "in_progress",
- "priority": "high",
- "created_at": "2024-01-10T09:00:00Z",
- "updated_at": "2024-01-15T14:30:00Z",
- "task_cost": {
- "cost": 50000,
- "cost_load_mode": "front"
}
}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
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
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 | |||||
| |||||
{- "task_cost": {
- "cost": 50000,
- "cost_load_mode": "front"
}
}{- "id": 23456789,
- "name": "Design homepage mockup - v2",
- "project_id": 920883,
- "parent_group_id": 456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-20",
- "duration": 5,
- "percent_complete": 75,
- "status": "in_progress",
- "created_at": "2024-01-10T09:00:00Z",
- "updated_at": "2024-01-17T11:20:00Z",
- "task_cost": {
- "cost": 50000,
- "cost_load_mode": "front"
}
}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.
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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:
Use cases:
Note: This operation cannot be reversed automatically. The task ID becomes a group ID after conversion.
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| flatten_children | boolean Example: flatten_children=true Whether to flatten nested groups into a flat list structure |
{- "id": 456790,
- "name": "Design homepage mockup",
- "project_id": 920883,
- "parent_group_id": 456789,
- "sort": 1,
- "is_collapsed": false,
- "children": [ ]
}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:
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| 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 |
[- {
- "id": 78901,
- "task_id": 23456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-17",
- "hours": 24,
- "resource_id": 1000
}, - {
- "id": 78902,
- "task_id": 23456789,
- "start_date": "2024-01-18",
- "end_date": "2024-01-20",
- "hours": 24,
- "resource_id": 1000
}, - {
- "id": 78903,
- "task_id": 23456789,
- "start_date": "2024-01-18",
- "end_date": "2024-01-19",
- "hours": 16,
- "resource_id": 1001
}
]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:
What does NOT get duplicated:
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
{- "id": 23456791,
- "name": "Design homepage mockup",
- "project_id": 920883,
- "parent_group_id": 456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-20",
- "duration": 5,
- "percent_complete": 0,
- "color": "blue1",
- "type": "task",
- "created_at": "2024-01-17T10:30:00Z",
- "updated_at": "2024-01-17T10:30:00Z"
}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.
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Lists all materials on a task.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the task
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
[- {
- "id": 78901,
- "task_id": 23456789,
- "name": "Double-pane windows",
- "lead_time": {
- "months": 0,
- "weeks": 2,
- "days": 0
}, - "purchaser": {
- "id": 1000,
- "first_name": "Jane",
- "last_name": "Doe"
}, - "status": "ordered",
- "ordered_on": "2024-02-01",
- "attached_documents": [ ]
}
]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.
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
Material data to create
| name required | string [ 1 .. 255 ] characters Name/description of the material | ||||||
required | object Lead time breakdown for the material | ||||||
| |||||||
| 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 | ||||||
{- "name": "Windows",
- "lead_time": {
- "months": 0,
- "weeks": 1,
- "days": 4
}, - "purchaser_id": 1000,
- "status": "not_ordered"
}{- "id": 78901,
- "task_id": 23456789,
- "name": "Windows",
- "lead_time": {
- "months": 0,
- "weeks": 1,
- "days": 4
}, - "purchaser": {
- "id": 1000,
- "first_name": "Jane",
- "last_name": "Doe"
}, - "status": "not_ordered",
- "ordered_on": null,
- "attached_documents": [ ]
}Assigns one resource to many tasks in a single request.
Authentication required: Yes (Bearer token)
Permissions: Only tasks the user can edit are changed; others are silently skipped.
Behavior:
| task_ids required | Array of integers IDs of the tasks to assign the resource to | ||||
required | object (BulkResourceRef) Reference to a resource by type and ID | ||||
| |||||
{- "task_ids": [
- 23456789,
- 23456790
], - "resource": {
- "type": "user",
- "type_id": 1000
}
}[- {
- "task_id": 23456789,
- "resource": {
- "id": 123456,
- "task_id": 23456789,
- "project_id": 920883,
- "type": "user",
- "type_id": 1000,
- "name": "John Doe",
- "color": "blue1",
- "is_disabled": false,
- "raci_roles": "R",
- "schedule_confirmation": {
- "id": 555,
- "status": "not_notified"
}, - "hours_per_day": 8,
- "total_hours": 40
}
}
]Removes one or more resources from many tasks in a single request. This uses POST rather than DELETE because it takes a request body.
Authentication required: Yes (Bearer token)
Permissions: Only tasks the user can edit are changed; others are silently skipped.
Returns 400 if no matching assignment was found.
| task_ids required | Array of integers IDs of the tasks to remove resources from | ||||
required | Array of objects (BulkResourceRef) | ||||
Array
| |||||
{- "task_ids": [
- 23456789,
- 23456790
], - "resources": [
- {
- "type": "user",
- "type_id": 1000
}
]
}[- {
- "task_id": 23456789,
- "resource_id": 123456
}
]Re-validates the given dependencies and reschedules their successor tasks so the schedule satisfies them. Circular dependencies are detected along the way.
Authentication required: Yes (Bearer token)
Behavior: Follows the dependency chain (up to 50 levels deep) from each dependency's tasks. Returns 204 with no body, including when none of the IDs exist. If a circular dependency or other scheduling error is found, the API returns 400 with an error message.
Use cases:
| ids required | Array of integers IDs of the dependencies to fix |
{- "ids": [
- 12345,
- 12346
]
}{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}Changes the type or lead/lag time of an existing dependency. At least one of lead_lag_time or type is required.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the task's project
Advanced dependency types: Changing a basic (FS) dependency to SS, FF or SF requires the Advanced Dependencies feature; otherwise the API returns 402.
Response: The updated dependency is returned directly (not wrapped in data).
| dependencyId required | integer >= 1 Example: 12345 Unique identifier of the task dependency |
| lead_lag_time | integer Lead or lag time in days (positive for lag, negative for lead) |
| type | string Enum: "FS" "SS" "FF" "SF" Type of dependency. SS, FF and SF require the Advanced Dependencies feature. |
{- "lead_lag_time": 2,
- "type": "SS"
}{- "id": 12345,
- "project_id": 920883,
- "from_task": {
- "id": 23456789,
- "name": "Design homepage mockup",
- "users": [
- {
- "id": 123,
- "name": "Jane Doe",
- "pic": "string"
}
], - "color": "blue2",
- "type": "task",
- "percent_complete": 0
}, - "to_task": {
- "id": 23456789,
- "name": "Design homepage mockup",
- "users": [
- {
- "id": 123,
- "name": "Jane Doe",
- "pic": "string"
}
], - "color": "blue2",
- "type": "task",
- "percent_complete": 0
}, - "lead_lag_time": 0,
- "type": "FS"
}Previews how resource hours would be redistributed if the task's estimated hours changed to a new value. Nothing is saved.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the task
The response compares original, total_hours_keep (assigned hours stay as they are, so the difference shows up as unassigned hours) and total_hours_adjust (assigned hours are scaled proportionally to the new estimate).
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| estimated_hours required | number Example: estimated_hours=40 New estimated hours for the task |
{- "original": { },
- "total_hours_keep": { },
- "total_hours_adjust": { }
}Previews the effect of setting a task to start on start_date and last days working days. The end date is computed from the project's working days and holidays. Nothing is saved.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the task's project
The response compares original, total_hours_keep (total hours stay, hours per day change) and total_hours_adjust (hours per day stay, total hours change). Returns null if the task doesn't use estimated hours.
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| start_date required | string <date> Example: start_date=2024-02-01 New start date |
| days required | integer Example: days=5 New duration in working days |
{- "original": { },
- "total_hours_keep": { },
- "total_hours_adjust": { }
}Previews the effect of moving a task to the given start and end dates. Nothing is saved.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the task's project
The response compares original, total_hours_keep and total_hours_adjust, as in the days preview. Returns null if the task doesn't use estimated hours.
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| start_date required | string <date> Example: start_date=2024-02-01 New start date |
| end_date required | string <date> Example: end_date=2024-02-07 New end date |
{- "original": { },
- "total_hours_keep": { },
- "total_hours_adjust": { }
}Updates a material on a task. All fields are optional, but the body must not be empty (an empty body returns 422).
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the task's project
Validation: If lead_time is sent, months, weeks and days are all required and at least one must be greater than 0. purchaser_id must be an active user on the project, or null.
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| materialId required | integer >= 1 Example: 78901 Unique identifier of the material |
| name | string New name of the material | ||||||
object New lead time. When provided, months, weeks and days are all required and at least one must be greater than 0. | |||||||
| |||||||
| purchaser_id | integer or null ID of an active project user responsible for purchasing, or null to unassign | ||||||
| ordered_on | string or null <date> Date the material was ordered | ||||||
| status | string Enum: "not_ordered" "ordered" "delayed" "delivered" | ||||||
{- "status": "ordered",
- "ordered_on": "2024-02-01"
}{- "id": 78901,
- "task_id": 23456789,
- "name": "Double-pane windows",
- "lead_time": {
- "months": 0,
- "weeks": 2,
- "days": 0
}, - "purchaser": {
- "id": 1000,
- "first_name": "Jane",
- "last_name": "Doe"
}, - "status": "ordered",
- "ordered_on": "2024-02-01",
- "attached_documents": [ ]
}Deletes a material from a task.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the task's project
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| materialId required | integer >= 1 Example: 78901 Unique identifier of the material |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Attaches an existing document to a material, for example a quote or spec sheet. Upload the document first with the task documents endpoint.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the task's project
The body must include material_id matching the path, as well as document_id.
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| materialId required | integer >= 1 Example: 78901 Unique identifier of the material |
| document_id required | integer ID of the document to attach |
| material_id required | integer Must match the material ID in the path |
{- "document_id": 67890,
- "material_id": 78901
}{- "id": 78901,
- "task_id": 23456789,
- "name": "Double-pane windows",
- "lead_time": {
- "months": 0,
- "weeks": 2,
- "days": 0
}, - "purchaser": {
- "id": 1000,
- "first_name": "Jane",
- "last_name": "Doe"
}, - "status": "ordered",
- "ordered_on": "2024-02-01",
- "attached_documents": [ ]
}Detaches a document from a material.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the task's project
| taskId required | integer >= 1 Example: 12345 Unique identifier of the task |
| materialId required | integer >= 1 Example: 78901 Unique identifier of the material |
| documentId required | integer >= 1 Example: 67890 Unique identifier of the document |
| delete_document | boolean Default: false If true, also permanently deletes the document |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}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:
Response: Returns an array of template objects sorted by their sort order.
Note: To get templates organized by category, use GET /templates/groups instead.
[- {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "name": "Marketing Campaign Template",
- "description": "A comprehensive template for planning marketing campaigns",
- "template_group_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
- "sort": 1,
}
]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:
Sorting: Groups and templates within groups are sorted by their sort order.
Use Cases:
[- {
- "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
- "name": "Marketing",
- "description": "Templates for marketing projects",
- "sort": 1,
- "templates": [
- {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "name": "Marketing Campaign Template",
- "description": "A comprehensive template for planning marketing campaigns",
- "template_group_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
- "sort": 1
}
]
}
]Retrieves a single project template by ID.
Authentication required: Yes (Bearer token)
Use cases:
| templateId required | string <uuid> Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 Unique identifier of the template (UUID) |
{- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "name": "Marketing Campaign Template",
- "description": "A comprehensive template for planning marketing campaigns",
- "template_group_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
- "sort": 1
}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:
start_date and end_date to specify the reporting periodInclude 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:
| 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 |
[- { }
]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
Hours: Provide the total hours to log for this task on this date. This will create or update the time entry.
Use Cases:
Response: Returns the created or updated time block.
| taskId required | integer Example: 12345 ID of the task to log time for |
| date required | string <date> Example: 2024-01-15 Date to log time for (YYYY-MM-DD) |
| hours required | number [ 0 .. 24 ] Number of hours to log |
{- "hours": 5
}{- "id": 12345,
- "task_id": 12345,
- "start_date": "2020-06-11",
- "end_date": "2020-06-11",
- "hours": 5,
- "resource_id": 123
}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.
| 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) |
[- {
- "id": 12345,
- "task_id": 23456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-15",
- "hours": 8,
- "resource_id": 123
}
]Creates a new time block (time entry).
Authentication required: Yes (Bearer token)
Create Time Block:
task_id, start_time, and end_timeuser_id to create time for another user (requires project admin)Permissions:
Validation:
Response: Returns the newly created time block.
Note: To punch in (start an open time block), use POST /times/punch-in.
| 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) |
{- "task_id": 123,
- "start_time": "2016-06-17T09:00:00Z",
- "end_time": "2016-06-17T17:00:00Z"
}{- "id": 12345,
- "task_id": 123,
- "start_date": "2016-06-17",
- "end_date": "2016-06-17",
- "hours": 8,
- "resource_id": 123
}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).
[- {
- "id": 12345,
- "task_id": 23456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-15",
- "hours": 8,
- "resource_id": 123
}
]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.
{- "id": 12345,
- "task_id": 23456789,
- "start_date": "2024-01-15",
- "end_date": null,
- "hours": null,
- "resource_id": 123
}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.
[- {
- "id": 12345,
- "task_id": 23456789,
- "start_date": "2024-01-15",
- "end_date": null,
- "hours": null,
- "resource_id": 123
}
]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:
Response: Returns the newly created time block.
| task_id required | integer ID of the task to log time for |
{- "task_id": 123
}{- "id": 12345,
- "task_id": 123,
- "start_date": "2016-06-17",
- "end_date": null,
- "hours": null,
- "resource_id": 123
}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 startedend_time: Change when the time block endedtask_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:
Response: Returns the updated time block.
| timeId required | integer Example: 12345 ID of the time block to update |
| 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 |
{- "start_time": "2009-01-01T09:00:00Z",
- "end_time": "2009-01-01T17:00:00Z"
}{- "id": 78901,
- "task_id": 23456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-17",
- "hours": 24,
- "resource_id": 1000
}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.
| timeId required | integer Example: 12345 ID of the time block to delete |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}Deprecated alias for POST /times/{timeId}/punch-out. Ends an open time block by setting its end time to now.
Authentication required: Yes (Bearer token)
Permissions: User must own the time block or have admin access to the project
Required parameter: punch_out must be present (any value) in the query string or body, otherwise the API returns 422. Use the dedicated punch-out endpoint instead.
Errors: 403 if the time block doesn't exist or can't be edited; 405 if the time block is already closed.
| timeId required | integer Example: 12345 ID of the time block to punch out |
| punch_out required | string Example: punch_out=1 Must be present; its value is ignored |
{- "id": 78901,
- "task_id": 23456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-17",
- "hours": 24,
- "resource_id": 1000
}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.
| timeId required | integer Example: 12345 ID of the time block to punch out |
{- "id": 222,
- "task_id": 123,
- "start_date": "2024-01-17",
- "end_date": "2024-01-17",
- "hours": 8,
- "resource_id": 123
}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 createdtask_updated: When a task is updatedtask_deleted: When a task is deletedTarget 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:
Response: Returns the newly created webhook subscription.
| 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 |
{- "target_type": "project",
- "target_id": 1000,
- "events": [
- "task_updated"
],
}{- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "target_type": "project",
- "target_id": 1000,
- "events": [
- "task_updated"
], - "created_by": 123,
- "created_at": "2024-01-15T10:30:00Z"
}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.
[- {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "target_type": "project",
- "target_id": 1000,
- "events": [
- "task_updated",
- "task_created"
], - "created_by": 123,
- "created_at": "2024-01-15T10:30:00Z"
}
]Retrieves one of your webhooks, including its subscribed events.
Authentication required: Yes (Bearer token)
Permissions: Only webhooks you created are visible; others return 404.
| id required | string <uuid> Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 Unique identifier of the webhook (UUID) |
{- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "target_type": "project",
- "target_id": 920883,
- "created_by": 123,
- "events": [
- "task_created",
- "task_updated",
- "task_deleted"
], - "created_at": "2024-01-15T10:30:00Z"
}Deletes a webhook so it stops receiving events.
Authentication required: Yes (Bearer token)
Permissions: Only webhooks you created can be deleted; others return 404.
| id required | string <uuid> Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 Unique identifier of the webhook (UUID) |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}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:
Grouping: Use group_by parameter to group results:
day: Daily breakdown (default)week: Weekly totalsmonth: Monthly totalsDate 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.
| userId required | integer >= 1 Example: 123 Unique identifier of the user |
| 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 |
{- "type": "user",
- "type_id": 123,
- "data": [
- {
- "date": "2024-01-15",
- "hours": 8,
- "tasks": [ ]
}, - {
- "date": "2024-01-16",
- "hours": 6.5,
- "tasks": [ ]
}
]
}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 totalsmonth: Monthly totalsDate 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.
| 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 |
[- {
- "type": "user",
- "type_id": 123,
- "data": [
- {
- "date": "2024-01-15",
- "hours": 8,
- "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:
project_ids (comma-separated) to filter to specific projectsGrouping: Use group_by to aggregate unassigned work:
day: Daily breakdown (default)week: Weekly totalsmonth: Monthly totalsUse Cases:
Response: Returns a workload data object with type 'unassigned' and hour allocations.
| 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 |
{- "type": "unassigned",
- "type_id": null,
- "data": [
- {
- "date": "2024-01-15",
- "hours": 16,
- "tasks": [ ]
}, - {
- "date": "2024-01-16",
- "hours": 12,
- "tasks": [ ]
}
]
}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 aggregationstart_date / end_date: Date rangeproject_id / project_ids: Project filteringResponse: Returns an array of workload data objects, one for each requested company resource.
| 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 |
[- {
- "type": "user",
- "type_id": 123,
- "data": [
- {
- "date": "2024-01-15",
- "hours": 8,
- "tasks": [
- { }
]
}
]
}
]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 aggregationstart_date / end_date: Date rangeproject_id / project_ids: Project filteringResponse: Returns an array of workload data objects, one for each requested project resource.
| 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 |
[- {
- "type": "user",
- "type_id": 123,
- "data": [
- {
- "date": "2024-01-15",
- "hours": 8,
- "tasks": [
- { }
]
}
]
}
]Retrieves all subcontractors belonging to a company.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the company
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
[- {
- "id": 12345,
- "company_id": 123456,
- "name": "Acme Electrical",
- "company_name": "Acme Subcontracting LLC",
- "trade": "Electrical",
- "phone_number": {
- "phone_number": "(717) 555-0100",
- "sms_opted_in": false,
- "opted_in_at": "2019-08-24T14:15:22Z",
- "opt_in_method": "sms",
- "opted_out_at": "2019-08-24T14:15:22Z",
- "opt_out_method": "sms",
- "opt_in_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}, - "email_address": "dispatch@acme.example",
- "color": "blue1",
- "preferences": [
- {
- "key": "notification.primary_method",
- "type": "string",
- "value": "all"
}
]
}
]Creates a new subcontractor associated with a company.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the company
Feature required: subcontractor_communications
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| name | string <= 255 characters |
| company_name | string or null <= 255 characters |
| trade | string <= 255 characters |
| phone | string or null <= 255 characters Phone number (normalized to E.164 by the API when provided). |
| email_address | string or null <email> <= 255 characters |
{- "name": "ABC Electrical",
- "company_name": "ABC Electric Co.",
- "trade": "Electrical",
- "phone": "+15555551234",
- "email_address": "contact@abcelectric.com"
}{- "id": 12345,
- "company_id": 123456,
- "name": "Acme Electrical",
- "company_name": "Acme Subcontracting LLC",
- "trade": "Electrical",
- "phone_number": {
- "phone_number": "(717) 555-0100",
- "sms_opted_in": false,
- "opted_in_at": "2019-08-24T14:15:22Z",
- "opt_in_method": "sms",
- "opted_out_at": "2019-08-24T14:15:22Z",
- "opt_out_method": "sms",
- "opt_in_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}, - "email_address": "dispatch@acme.example",
- "color": "blue1",
- "preferences": [
- {
- "key": "notification.primary_method",
- "type": "string",
- "value": "all"
}
]
}Retrieves a specific subcontractor by ID within a company.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the company
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| subcontractorId required | integer >= 1 Example: 12345 Unique identifier of the subcontractor |
{- "id": 12345,
- "company_id": 123456,
- "name": "Acme Electrical",
- "company_name": "Acme Subcontracting LLC",
- "trade": "Electrical",
- "phone_number": {
- "phone_number": "(717) 555-0100",
- "sms_opted_in": false,
- "opted_in_at": "2019-08-24T14:15:22Z",
- "opt_in_method": "sms",
- "opted_out_at": "2019-08-24T14:15:22Z",
- "opt_out_method": "sms",
- "opt_in_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}, - "email_address": "dispatch@acme.example",
- "color": "blue1",
- "preferences": [
- {
- "key": "notification.primary_method",
- "type": "string",
- "value": "all"
}
]
}Updates an existing subcontractor's details within a company.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the company
Note: If the phone number changes, the subcontractor must re-opt-in to SMS for TCPA compliance.
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| subcontractorId required | integer >= 1 Example: 12345 Unique identifier of the subcontractor |
| name | string <= 255 characters |
| company_name | string or null <= 255 characters |
| trade | string <= 255 characters |
| phone | string or null <= 255 characters Phone number (normalized to E.164 by the API when provided). |
| email_address | string or null <email> <= 255 characters |
{- "name": "Acme Electrical",
- "company_name": "Acme Subcontracting LLC",
- "trade": "Electrical",
- "phone": "+17175550100",
- "email_address": "dispatch@acme.example"
}{- "id": 12345,
- "company_id": 123456,
- "name": "Acme Electrical",
- "company_name": "Acme Subcontracting LLC",
- "trade": "Electrical",
- "phone_number": {
- "phone_number": "(717) 555-0100",
- "sms_opted_in": false,
- "opted_in_at": "2019-08-24T14:15:22Z",
- "opt_in_method": "sms",
- "opted_out_at": "2019-08-24T14:15:22Z",
- "opt_out_method": "sms",
- "opt_in_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}, - "email_address": "dispatch@acme.example",
- "color": "blue1",
- "preferences": [
- {
- "key": "notification.primary_method",
- "type": "string",
- "value": "all"
}
]
}Permanently deletes a subcontractor from the company.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the company
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| subcontractorId required | integer >= 1 Example: 12345 Unique identifier of the subcontractor |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}Creates or updates a preference setting for a specific subcontractor.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the company
Common preference keys: notification_primary_method (values: email, sms, all, none)
| companyId required | integer >= 1 Example: 123456 Unique identifier of the company |
| subcontractorId required | integer >= 1 Example: 12345 Unique identifier of the subcontractor |
| key required | string |
| type required | string Enum: "boolean" "number" "string" |
required | boolean or number or string Preference value (typed according to |
One of boolean Preference value (typed according to | |
{- "key": "notification_primary_method",
- "value": "email",
- "type": "string"
}{- "key": "notification.primary_method",
- "type": "string",
- "value": "all"
}Retrieves all subcontractors assigned to a project.
Authentication required: Yes (Bearer token)
Permissions: User must have access to the project
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
[- {
- "id": 12345,
- "company_id": 123456,
- "name": "Acme Electrical",
- "company_name": "Acme Subcontracting LLC",
- "trade": "Electrical",
- "phone_number": {
- "phone_number": "(717) 555-0100",
- "sms_opted_in": false,
- "opted_in_at": "2019-08-24T14:15:22Z",
- "opt_in_method": "sms",
- "opted_out_at": "2019-08-24T14:15:22Z",
- "opt_out_method": "sms",
- "opt_in_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}, - "email_address": "dispatch@acme.example",
- "color": "blue1",
- "preferences": [
- {
- "key": "notification.primary_method",
- "type": "string",
- "value": "all"
}
]
}
]Assigns an existing company subcontractor to a project.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the project
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| subcontractor_id required | integer >= 1 |
| color | string or null |
{- "subcontractor_id": 42,
- "color": "#FF5733"
}{- "project_id": 920883,
- "subcontractor_id": 12345,
- "color": "blue1",
- "subcontractor": {
- "id": 12345,
- "company_id": 123456,
- "name": "Acme Electrical",
- "company_name": "Acme Subcontracting LLC",
- "trade": "Electrical",
- "phone_number": {
- "phone_number": "(717) 555-0100",
- "sms_opted_in": false,
- "opted_in_at": "2019-08-24T14:15:22Z",
- "opt_in_method": "sms",
- "opted_out_at": "2019-08-24T14:15:22Z",
- "opt_out_method": "sms",
- "opt_in_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}, - "email_address": "dispatch@acme.example",
- "color": "blue1",
- "preferences": [
- {
- "key": "notification.primary_method",
- "type": "string",
- "value": "all"
}
]
}
}Updates a subcontractor's project-specific settings (e.g., color).
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the project
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| subcontractorId required | integer >= 1 Example: 12345 Unique identifier of the subcontractor |
| color | string or null |
{- "color": "#3498DB"
}{- "project_id": 920883,
- "subcontractor_id": 12345,
- "color": "blue1",
- "subcontractor": {
- "id": 12345,
- "company_id": 123456,
- "name": "Acme Electrical",
- "company_name": "Acme Subcontracting LLC",
- "trade": "Electrical",
- "phone_number": {
- "phone_number": "(717) 555-0100",
- "sms_opted_in": false,
- "opted_in_at": "2019-08-24T14:15:22Z",
- "opt_in_method": "sms",
- "opted_out_at": "2019-08-24T14:15:22Z",
- "opt_out_method": "sms",
- "opt_in_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}, - "email_address": "dispatch@acme.example",
- "color": "blue1",
- "preferences": [
- {
- "key": "notification.primary_method",
- "type": "string",
- "value": "all"
}
]
}
}Removes a subcontractor's assignment from a project.
Authentication required: Yes (Bearer token)
Permissions: User must have edit access to the project
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| subcontractorId required | integer >= 1 Example: 12345 Unique identifier of the subcontractor |
{- "error": {
- "message": "Authentication required. Please provide a valid API token.",
- "code": "UNAUTHORIZED"
}
}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:
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.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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) |
{- "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "permission": "admin",
- "message": "Welcome to the project!",
- "send_invite": true
}{- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "permission": "admin",
- "team": {
- "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "name": "Development Team",
- "company_id": 1000
}
}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:
Response: Returns an array of RACI role assignments showing which users have which roles for each task, group, or project.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
[- {
- "id": 12345,
- "project_id": 920883,
- "target_type": "task",
- "target_id": 23456789,
- "resource_type": "user",
- "resource_id": 123,
- "roles": "RA"
}, - {
- "id": 12346,
- "project_id": 920883,
- "target_type": "task",
- "target_id": 23456789,
- "resource_type": "user",
- "resource_id": 124,
- "roles": "C"
}
]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:
Validation:
target_type must be "task", "group", or "project"resource_type must be "user" (currently only users are supported)Response: Returns the created or updated RACI role assignment.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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. |
{- "project_id": 1000,
- "target_type": "task",
- "target_id": 12345,
- "resource_type": "user",
- "resource_id": 1000,
- "roles": [
- "R",
- "A"
]
}{- "id": 12345,
- "project_id": 1000,
- "target_type": "task",
- "target_id": 12345,
- "resource_type": "user",
- "resource_id": 1000,
- "roles": "RA"
}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:
Response: Returns an object with three arrays, one for each resource type.
Use Cases:
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
{- "user_resources": [
- {
- "id": 123,
- "first_name": "John",
- "last_name": "Doe",
- "color": "blue1"
}
], - "company_resources": [
- {
- "id": 2754313,
- "name": "Conference Room A",
- "company_id": 1000
}
], - "project_resources": [
- {
- "id": 12345,
- "name": "Project Laptop",
- "project_id": 920883,
- "color": "green1",
- "created_at": "2024-01-15T10:30:00Z"
}
]
}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:
Note: This endpoint is functionally identical to /projects/{projectId}/resource_options. Use that endpoint instead for consistency.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
{- "user_resources": [
- { }
], - "company_resources": [
- {
- "id": 5000,
- "company_id": 123456,
- "name": "Conference Room A",
- "created_at": "2024-01-10T09:00:00Z"
}
], - "project_resources": [
- {
- "id": 12345,
- "project_id": 920883,
- "name": "Conference Room A",
- "color": "blue1",
- "created_at": "2024-01-15T10:30:00Z"
}
]
}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.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
[- {
- "id": 12345,
- "project_id": 920883,
- "name": "Conference Room A",
- "color": "blue2",
- "created_at": "2024-01-15T10:30:00Z"
}
]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:
Response: Returns the newly created project resource.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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 |
{- "name": "Project Resource",
- "color": "green1"
}{- "id": 12345,
- "project_id": 920883,
- "name": "Project Resource",
- "color": "green1",
- "created_at": "2024-01-15T10:30:00Z"
}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
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
{- "id": 12345,
- "project_id": 920883,
- "name": "Conference Room A",
- "color": "blue1",
- "created_at": "2024-01-15T10:30:00Z"
}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
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| name required | string [ 1 .. 255 ] characters Updated name of the resource |
{- "name": "Updated Resource"
}{- "id": 12345,
- "project_id": 920883,
- "name": "Conference Room A",
- "color": "blue1",
- "created_at": "2024-01-15T10:30:00Z"
}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
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
[- {
- "id": 12345,
- "project_id": 920883,
- "company_resource_id": 2754313,
- "color": "blue1",
- "resource": {
- "id": 5000,
- "company_id": 123456,
- "name": "Conference Room A",
- "created_at": "2024-01-10T09:00:00Z"
}
}
]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.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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 |
{- "company_resource_id": 1,
- "color": "blue2"
}{- "id": 12345,
- "project_id": 920883,
- "company_resource_id": 2754313,
- "color": "blue1",
- "resource": {
- "id": 5000,
- "company_id": 123456,
- "name": "Conference Room A",
- "created_at": "2024-01-10T09:00:00Z"
}
}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
| 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) |
| 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 |
{- "company_resource_id": 1,
- "color": "blue2"
}{- "id": 12345,
- "project_id": 920883,
- "company_resource_id": 2754313,
- "color": "blue1",
- "resource": {
- "id": 5000,
- "company_id": 123456,
- "name": "Conference Room A",
- "created_at": "2024-01-10T09:00:00Z"
}
}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
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| companyId required | integer Example: 12345 ID of the company resource link |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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 aggregationstart_date / end_date: Date rangeproject_id / project_ids: Project filteringResponse: Returns an array of workload data objects, one for each requested company resource.
| 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 |
[- {
- "type": "user",
- "type_id": 123,
- "data": [
- {
- "date": "2024-01-15",
- "hours": 8,
- "tasks": [
- { }
]
}
]
}
]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 aggregationstart_date / end_date: Date rangeproject_id / project_ids: Project filteringResponse: Returns an array of workload data objects, one for each requested project resource.
| 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 |
[- {
- "type": "user",
- "type_id": 123,
- "data": [
- {
- "date": "2024-01-15",
- "hours": 8,
- "tasks": [
- { }
]
}
]
}
]Updates the project-specific settings for a company resource, such as the color override.
Authentication required: Yes (Bearer token)
Permissions: User must have edit permissions on the project
Updates: Currently only the color can be updated. The company_resource_id must be provided but cannot be changed.
Response: Returns the updated project-company resource link.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| company_resource_optionId required | integer >= 1 Example: 12345 Unique identifier of the company resource option link |
| 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 |
{- "company_resource_id": 2754313,
- "color": "green2"
}{- "id": 12345,
- "project_id": 920883,
- "company_resource_id": 2754313,
- "color": "green2",
- "resource": {
- "id": 2754313,
- "name": "Conference Room A",
- "company_id": 1000
}
}Removes a company resource from a project. The resource will no longer be available for task assignments in this project.
Authentication required: Yes (Bearer token)
Permissions: User must have edit permissions on the project
Effects:
Response: Returns 204 No Content on success.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| company_resource_optionId required | integer >= 1 Example: 12345 Unique identifier of the company resource option link |
{- "error": {
- "message": "Invalid request parameters",
- "code": "BAD_REQUEST",
- "details": {
- "field": "message",
- "issue": "Field is required"
}
}
}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.
Response: Returns a paginated list of time block objects.
| projectId required | integer >= 1 Example: 920883 Unique identifier of the project |
| 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) |
{- "timeblocks": [
- {
- "id": 78901,
- "task_id": 23456789,
- "start_date": "2024-01-15",
- "end_date": "2024-01-17",
- "hours": 24,
- "resource_id": 1000
}
], - "total": 120,
- "count": 50,
- "current_page": 1
}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:
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.
| ids[] required | Array of integers Example: ids[]=920883 Array of project IDs to export |
{- "id": 67890,
- "name": "project-export.csv",
- "created_at": "2024-01-15T10:30:00Z"
}Imports a new project from CSV data.
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.
Input: Provide the CSV contents as a raw string in csv_data.
| company_id required | integer ID of the company to import the project into |
| csv_data required | string Raw CSV data as a string (including header row if present) |
| has_hours_enabled | boolean Default: false Whether hour tracking should be enabled on the imported project |
{- "company_id": 1000,
- "has_hours_enabled": false,
- "csv_data": "WBS,Name,Type,Start Date,End Date,Color\n1,Website Redesign,Project,2024-01-01,2024-02-01,blue1\n1.1,Design,Group,,,green2\n1.1.1,Homepage mockups,Task,2024-01-02,2024-01-10,orange3\n"
}{- "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": [
- 1,
- 2,
- 3,
- 4,
- 5
], - "public_key": null,
- "permission": "admin",
- "is_starred": false,
- "created_at": "2024-01-01T00:00:00Z",
- "accesses": [
- {
- "id": 7070608,
- "project_id": 920884,
- "company_id": 1000,
- "user_id": 1960234,
- "user": { },
- "permission": "edit",
- "status": "Accepted",
- "project_status": "active",
- "color": "blue1",
- "custom_message": "Join the party!"
}
], - "teams": [
- {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "project_id": 920883,
- "team_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
- "permission": "admin",
- "team": {
- "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
- "name": "Development Team",
- "company_id": 123456,
- "created_at": "2024-01-10T09:00:00Z"
}
}
], - "company": { },
- "integrations": [
- { }
], - "metrics": { },
- "custom_fields": [
- {
- "id": 1001,
- "name": "PO Number",
- "type": "text",
- "options": [
- "A",
- "B"
], - "description": "Field for storing PO numbers"
}
]
}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:
Grouping: Use group_by parameter to group results:
day: Daily breakdown (default)week: Weekly totalsmonth: Monthly totalsDate 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.
| userId required | integer >= 1 Example: 123 Unique identifier of the user |
| 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 |
{- "type": "user",
- "type_id": 123,
- "data": [
- {
- "date": "2024-01-15",
- "hours": 8,
- "tasks": [ ]
}, - {
- "date": "2024-01-16",
- "hours": 6.5,
- "tasks": [ ]
}
]
}