# Projects API

This group covers projects and their members, tasks and sub-tasks, requests, areas, labels, milestones and work item types. Every call acts as a person: send a personal access token, or an OAuth access token from a person's sign-in (scope `Volobox`). An integration app's own client secret is refused with `403` (`Volobox:Integrations:MemberConnectionRequired`). Paths, tokens and conventions are in [API overview](/docs/api-overview).

## Projects

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/project` | `projects.project.getList` | Lists the projects the caller can open, filtered and one page at a time. |
| POST | `/api/v1/project` | `projects.project.create` | Creates a project with the caller as its admin. |
| GET | `/api/v1/project/{id}` | `projects.project.get` | Gets a project the caller can open. |
| PUT | `/api/v1/project/{id}` | `projects.project.update` | Changes a project's name, description, visibility and other settings. |
| POST | `/api/v1/project/{id}/archive` | `projects.project.archive` | Archives a project. |
| GET | `/api/v1/project/{id}/assignable-agents` | `projects.project.getAssignableAgents` | Lists the agents work items of a project can be assigned to. |
| GET | `/api/v1/project/{id}/assignable-users` | `projects.project.getAssignableMemberUsers` | Lists the people work items of a project can be assigned to. |
| POST | `/api/v1/project/{id}/change-slug` | `projects.project.changeSlug` | Changes the URL slug of a project. |
| POST | `/api/v1/project/{id}/delete` | `projects.project.delete` | Deletes a project; the caller confirms by naming it. |
| GET | `/api/v1/project/{id}/members` | `projects.project.getMembers` | Lists the members of a project with their roles. |
| POST | `/api/v1/project/{id}/members` | `projects.project.addMember` | Adds a person, group or agent to a project with a role. |
| PUT | `/api/v1/project/{id}/members/{memberId}` | `projects.project.updateMember` | Changes a project member's role. |
| DELETE | `/api/v1/project/{id}/members/{memberId}` | `projects.project.removeMember` | Removes a member from a project. |
| POST | `/api/v1/project/{id}/pin` | `projects.project.pin` | Pins or unpins a project for the caller. |
| POST | `/api/v1/project/{id}/unarchive` | `projects.project.unarchive` | Brings an archived project back. |
| GET | `/api/v1/project/by-slug/{slug}` | `projects.project.getBySlug` | Gets a project by its URL slug. |
| GET | `/api/v1/project/for-user/{userId}` | `projects.project.getForUser` | Lists the projects a person belongs to, limited to the ones the caller can open. |
| GET | `/api/v1/project/my-collaborations` | `projects.project.getMyCollaboratorProjects` | Lists the projects the caller collaborates on. Acts on the signed-in person's own account. |
| GET | `/api/v1/project/my-pinned` | `projects.project.getMyPinnedProjects` | Lists the projects the caller has pinned. Acts on the signed-in person's own account. |
| GET | `/api/v1/project/my-projects` | `projects.project.getMyProjects` | Lists the projects the caller is a member of. Acts on the signed-in person's own account. |
| GET | `/api/v1/project/my-shortcuts` | `projects.project.getMyShortcutProjects` | Lists the projects the caller keeps as shortcuts. Acts on the signed-in person's own account. |
| GET | `/api/v1/project/shared-with/{userId}` | `projects.project.getSharedWithUser` | Lists the projects the caller and another person both belong to. |

Request bodies:

- `CreateProjectDto` (`create`): requires `name` (string), `slug` (string).
- `UpdateProjectDto` (`update`): requires `name` (string).
- `UpdateProjectMemberDto` (`updateMember`): requires `role` (ProjectMemberRole: None, Viewer, Collaborator, Manager, Admin).

## Project areas

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/project-area` | `projects.projectArea.getList` | Lists the areas of a project, leaving archived ones out unless asked. |
| POST | `/api/v1/project-area` | `projects.projectArea.create` | Creates an area in a project. |
| GET | `/api/v1/project-area/{id}` | `projects.projectArea.get` | Gets one area of a project. |
| PUT | `/api/v1/project-area/{id}` | `projects.projectArea.update` | Changes an area of a project. |
| DELETE | `/api/v1/project-area/{id}` | `projects.projectArea.delete` | Deletes an area of a project. |
| POST | `/api/v1/project-area/{id}/archive` | `projects.projectArea.archive` | Archives an area so new work items can no longer be filed under it. |
| POST | `/api/v1/project-area/{id}/unarchive` | `projects.projectArea.unarchive` | Brings an archived area back into use. |

Request bodies:

- `CreateUpdateProjectAreaDto` (`create`, `update`): requires `backgroundColor` (string), `name` (string), `textColor` (string).

## Project labels

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/project-label` | `projects.projectLabel.getList` | Lists the labels of a project, archived ones included and flagged. |
| POST | `/api/v1/project-label` | `projects.projectLabel.create` | Creates a label in a project. |
| GET | `/api/v1/project-label/{id}` | `projects.projectLabel.get` | Gets one label of a project. |
| PUT | `/api/v1/project-label/{id}` | `projects.projectLabel.update` | Changes a label of a project. |
| DELETE | `/api/v1/project-label/{id}` | `projects.projectLabel.delete` | Deletes a label from a project, moving its work items to the replacement label given in the query string or else taking it off them. |
| POST | `/api/v1/project-label/{id}/archive` | `projects.projectLabel.archive` | Archives a label: it stays on the work items that carry it but cannot be added to another. |
| POST | `/api/v1/project-label/{id}/unarchive` | `projects.projectLabel.unarchive` | Brings an archived label back into use. |

Request bodies:

- `CreateUpdateProjectLabelDto` (`create`, `update`): requires `backgroundColor` (string), `name` (string), `textColor` (string).

## Project milestones

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/project-milestone` | `projects.projectMilestone.getList` | Lists the milestones of a project. |
| POST | `/api/v1/project-milestone` | `projects.projectMilestone.create` | Creates a milestone in a project. |
| GET | `/api/v1/project-milestone/{id}` | `projects.projectMilestone.get` | Gets one milestone of a project. |
| PUT | `/api/v1/project-milestone/{id}` | `projects.projectMilestone.update` | Changes a milestone's name, dates or description. |
| DELETE | `/api/v1/project-milestone/{id}` | `projects.projectMilestone.delete` | Deletes a milestone from a project. |
| POST | `/api/v1/project-milestone/{id}/close` | `projects.projectMilestone.close` | Closes a milestone. |
| POST | `/api/v1/project-milestone/{id}/reopen` | `projects.projectMilestone.reopen` | Reopens a closed milestone. |

Request bodies:

- `CreateUpdateProjectMilestoneDto` (`create`, `update`): requires `name` (string).

## Project requests

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/project-request` | `projects.projectRequest.getList` | Lists the requests of a project the caller can open, filtered and one page at a time. |
| POST | `/api/v1/project-request` | `projects.projectRequest.create` | Opens a request in a project. |
| GET | `/api/v1/project-request/{id}` | `projects.projectRequest.get` | Gets a request of a project the caller can open. |
| PUT | `/api/v1/project-request/{id}` | `projects.projectRequest.update` | Changes a request's title, assignees, labels and other fields. |
| DELETE | `/api/v1/project-request/{id}` | `projects.projectRequest.delete` | Deletes a request. |
| POST | `/api/v1/project-request/{id}/close` | `projects.projectRequest.close` | Closes a request with a reason. |
| POST | `/api/v1/project-request/{id}/create-task` | `projects.projectRequest.createTaskFromRequest` | Creates a task from a request and links the two. |
| PUT | `/api/v1/project-request/{id}/description` | `projects.projectRequest.updateDescription` | Replaces the description of a request. |
| GET | `/api/v1/project-request/{id}/linked-tasks` | `projects.projectRequest.getLinkedTasks` | Lists the tasks created from a request. |
| POST | `/api/v1/project-request/{id}/open` | `projects.projectRequest.open` | Reopens a closed request. |
| POST | `/api/v1/project-request/{id}/refresh-external` | `projects.projectRequest.refreshExternalRequest` | Reads a request linked to an external tracker from that tracker again. |
| POST | `/api/v1/project-request/{id}/start-agent-work` | `projects.projectRequest.startAgentWork` | Starts work by an agent already assigned to the request. |
| GET | `/api/v1/project-request/assigned-by-me` | `projects.projectRequest.getAssignedByMe` | Lists the requests the caller assigned to others, one page at a time. |
| POST | `/api/v1/project-request/attach-to-task` | `projects.projectRequest.attachToTask` | Links requests of a project to one of its open tasks; each request is in progress until the task closes. |
| GET | `/api/v1/project-request/by-assignee` | `projects.projectRequest.getByAssignee` | Lists the requests assigned to a person across the projects the caller can open, one page at a time. |
| GET | `/api/v1/project-request/by-key/{slug}/{number}` | `projects.projectRequest.getByKey` | Gets a request by its project slug and number, together with its project. |
| POST | `/api/v1/project-request/create-task` | `projects.projectRequest.createTaskFromRequests` | Creates one task from several requests of a project and links each of them to it. Fields left empty come from the requests; each request is in progress until the task closes. |
| GET | `/api/v1/project-request/resolve-default-assignee` | `projects.projectRequest.resolveDefaultAssignee` | Tells who a new request in a project, or in one of its areas, would be assigned to. |

Request bodies:

- `CreateProjectRequestDto` (`create`): requires `projectId` (uuid), `title` (string).
- `UpdateProjectRequestDto` (`update`): requires `title` (string).
- `CreateTaskFromRequestDto` (`createTaskFromRequest`): requires `title` (string).
- `UpdateWorkItemDescriptionDto` (`updateDescription`): no field is required.
- `CreateTaskFromRequestsDto` (`createTaskFromRequests`): requires `title` (string).

## Request assignments

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| POST | `/api/v1/project-request-assignment/{assigneeId}/add-to-agenda` | `projects.projectRequestAssignment.addToAgenda` | Adds a request assigned to the caller to their agenda and resolves the assignment's Inbox card. |

## Project tasks

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/project-task` | `projects.projectTask.getList` | Lists the tasks of a project the caller can open, filtered and one page at a time. |
| POST | `/api/v1/project-task` | `projects.projectTask.create` | Creates a task in a project. |
| GET | `/api/v1/project-task/{id}` | `projects.projectTask.get` | Gets a task of a project the caller can open. |
| PUT | `/api/v1/project-task/{id}` | `projects.projectTask.update` | Changes a task's title, status, assignees, labels, dates and other fields. |
| DELETE | `/api/v1/project-task/{id}` | `projects.projectTask.delete` | Deletes a task. |
| POST | `/api/v1/project-task/{id}/blocking-link` | `projects.projectTask.addBlockingLink` | Records that a task blocks or is blocked by another task. |
| GET | `/api/v1/project-task/{id}/children` | `projects.projectTask.getChildren` | Lists the sub-tasks of a task. |
| POST | `/api/v1/project-task/{id}/close` | `projects.projectTask.close` | Closes a task with an optional reason. |
| PUT | `/api/v1/project-task/{id}/description` | `projects.projectTask.updateDescription` | Replaces the description of a task. |
| POST | `/api/v1/project-task/{id}/draft` | `projects.projectTask.moveToDraft` | Moves a task back to draft. |
| GET | `/api/v1/project-task/{id}/links` | `projects.projectTask.getTaskLinks` | Lists the tasks a task blocks, is blocked by or is related to. |
| DELETE | `/api/v1/project-task/{id}/links/{linkId}` | `projects.projectTask.removeTaskLink` | Removes a link between two tasks. |
| GET | `/api/v1/project-task/{id}/move-preview` | `projects.projectTask.previewMove` | Previews what moving a task and its sub-tasks to another project would change. |
| POST | `/api/v1/project-task/{id}/move-to-project` | `projects.projectTask.moveToProject` | Moves a task and its sub-tasks to another project. |
| POST | `/api/v1/project-task/{id}/promote` | `projects.projectTask.promote` | Turns a sub-task into a top-level task. |
| POST | `/api/v1/project-task/{id}/refresh-external` | `projects.projectTask.refreshExternalTask` | Reads a task linked to an external tracker from that tracker again. |
| POST | `/api/v1/project-task/{id}/related-link` | `projects.projectTask.addRelatedLink` | Records that a task is related to another task. |
| POST | `/api/v1/project-task/{id}/reopen` | `projects.projectTask.reopen` | Reopens a closed task. |
| POST | `/api/v1/project-task/{id}/reorder-children` | `projects.projectTask.reorderChildren` | Puts the sub-tasks of a task in the given order. |
| POST | `/api/v1/project-task/{id}/set-parent` | `projects.projectTask.setParent` | Makes a task a sub-task of another task, or takes it out of its parent. |
| GET | `/api/v1/project-task/{id}/source-requests` | `projects.projectTask.getSourceRequests` | Lists the requests a task was made from or given, oldest link first. |
| POST | `/api/v1/project-task/{id}/source-requests/{requestId}` | `projects.projectTask.addSourceRequest` | Links a request of the task's project to an open task; the request is in progress until the task closes. |
| DELETE | `/api/v1/project-task/{id}/source-requests/{requestId}` | `projects.projectTask.removeSourceRequest` | Unlinks a request from a task; the request's status follows the tasks still linked to it. |
| POST | `/api/v1/project-task/{id}/start-agent-work` | `projects.projectTask.startAgentWork` | Starts work by an agent already assigned to the task. |
| POST | `/api/v1/project-task/{id}/work-state` | `projects.projectTask.setWorkState` | Sets the work state of a task. |
| GET | `/api/v1/project-task/by-assignee` | `projects.projectTask.getByAssignee` | Lists the tasks assigned to a person across the projects the caller can open, one page at a time. |
| GET | `/api/v1/project-task/by-group` | `projects.projectTask.getByGroup` | Lists the tasks assigned to a group across the projects the caller can open, one page at a time. |
| GET | `/api/v1/project-task/by-key/{slug}/{number}` | `projects.projectTask.getByKey` | Gets a task by its project slug and number, together with its project. |

Request bodies:

- `CreateProjectTaskDto` (`create`): requires `projectId` (uuid), `title` (string).
- `UpdateProjectTaskDto` (`update`): requires `title` (string).
- `UpdateWorkItemDescriptionDto` (`updateDescription`): no field is required.

## Task assignments

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| POST | `/api/v1/project-task-assignment/{assigneeId}/add-to-agenda` | `projects.projectTaskAssignment.addToAgenda` | Adds a task assigned to the caller to their agenda and resolves the assignment's Inbox card. |

## Work item types

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/project-work-item-type` | `projects.projectWorkItemType.getList` | Lists the work item types of a project. |
| POST | `/api/v1/project-work-item-type` | `projects.projectWorkItemType.create` | Creates a work item type in a project. |
| GET | `/api/v1/project-work-item-type/{id}` | `projects.projectWorkItemType.get` | Gets one work item type of a project. |
| PUT | `/api/v1/project-work-item-type/{id}` | `projects.projectWorkItemType.update` | Changes a work item type of a project. |
| DELETE | `/api/v1/project-work-item-type/{id}` | `projects.projectWorkItemType.delete` | Deletes a work item type, moving its work items to the replacement type given in the query string. |
| POST | `/api/v1/project-work-item-type/{id}/archive` | `projects.projectWorkItemType.archive` | Archives a work item type: it stays on the work items that carry it but cannot be given to another. |
| POST | `/api/v1/project-work-item-type/{id}/unarchive` | `projects.projectWorkItemType.unarchive` | Brings an archived work item type back into use. |

Request bodies:

- `CreateUpdateProjectWorkItemTypeDto` (`create`, `update`): requires `backgroundColor` (string), `icon` (string), `name` (string), `textColor` (string).

## Example

`projects.project.getList`: lists the projects the caller can open, filtered and one page at a time.

```bash title="curl"
curl -s "https://volobox.example.com/api/v1/project?SkipCount=0&MaxResultCount=20" \
  -H "Authorization: Bearer $VOLOBOX_TOKEN"
```

`SkipCount` is how many items to skip and `MaxResultCount` how many to return. The answer carries `totalCount` and the page of `items`.
