HTTP API

Reference

Projects API

Endpoints for projects and their members, tasks, requests, areas, labels, milestones and work item types.

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.

Projects

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

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

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

Request bodies:

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

Project labels

GET/api/v1/project-label
Lists the labels of a project, archived ones included and flagged.
projects.projectLabel.getList
POST/api/v1/project-label
Creates a label in a project.
projects.projectLabel.create
GET/api/v1/project-label/{id}
Gets one label of a project.
projects.projectLabel.get
PUT/api/v1/project-label/{id}
Changes a label of a project.
projects.projectLabel.update
DELETE/api/v1/project-label/{id}
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.
projects.projectLabel.delete
POST/api/v1/project-label/{id}/archive
Archives a label: it stays on the work items that carry it but cannot be added to another.
projects.projectLabel.archive
POST/api/v1/project-label/{id}/unarchive
Brings an archived label back into use.
projects.projectLabel.unarchive

Request bodies:

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

Project milestones

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

Request bodies:

  • CreateUpdateProjectMilestoneDto (create, update): requires name (string).

Project requests

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

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

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

Project tasks

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

Request bodies:

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

Task assignments

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

Work item types

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

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.

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.