Documentation

Projects API

Table of Contents

Overview

QReserve's project management features allow users, reservations and files to be grouped together to track a project's progress, results and outcomes.

GET Endpoints

Query Projects

GET /projects/{site_id}
GET /projects

Retrieves a list of projects for a site. By default, it only returns the projects which a user is a member of. If the user is a site admin for the site, they can use the all_projects flag to pull down all the projects for a site.

Path Parameters

Parameter Type Required Description
site_id string No Site ID where the projects will be retrieved from. If not provided, it will default to retrieving all projects accessible by the authenticated user

Query Parameters

Parameter Type Description
all_projects boolean When True, will set all_projects to True for admins and just search a user's own projects for regular users
all_projects_for_site_or_user boolean When True, will set all_projects to True for admins and just search a user's own projects for regular users
count_only boolean When True, only numitems is returned, with the data field being left empty
created_end integer Unix timestamp representing the end of creation date range
created_start integer Unix timestamp representing the start of creation date range
exclude_view_only boolean Excludes projects that are view-only
for_kiosks boolean Limits project data to only what is needed for kiosks
from_user_view string User ID to view projects from the perspective of another user. Requires site administrator or moderator privileges
include_creator boolean Includes the creator information in the response. Requires all_projects flag to be set
include_tags boolean Includes project tags in the response
inject_project_id string Injects a specific project into the response
last_modified_end integer Unix timestamp representing the end of last modified date range
last_modified_start integer Unix timestamp representing the start of last modified date range
limit integer Limits the number of projects returned
offset integer Offsets the starting point for retrieving projects
only_active boolean Only returns active projects. Default is True
only_inactive boolean Only returns inactive projects
project_id string Filters by project ID
project_ids array of strings Filters by multiple project IDs
project_tag_ids array of strings Filters by project tag IDs
reservable_id string Filters by reservable ID
search string Searches for projects by name or description
search_limited string Limited search for projects by name or description
sort_atr string Sorts projects by a specific attribute. Allowed values: site_name, name, created_at, last_modified_at
sort_ord string Sort order for the specified attribute. Allowed values: asc, desc
status string Filters by project status
statuses array of strings Filters by multiple project statuses
user_id string Filters by user ID
usergroup_id integer Filters by user group ID

Response

Success Response (200 OK)

A list of project data in JSON format.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to retrieve projects on this site

Get Project

GET /project/{project_id}

Retrieves a specific project by its ID. Site administrators or project members are allowed to access this endpoint.

Path Parameters

Parameter Type Required Description
project_id string Yes The ID of the project to retrieve

Query Parameters

Parameter Type Default Description
include_tags boolean false Whether to include tags in the response

Response

Success Response (200 OK)

Project data in JSON format.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User is not a site moderator or project member, or site projects are restricted to admins only
  • 404 Not Found: Project with the specified ID does not exist

Note: Site moderators can access any project within their site. Non-moderators must be members of the project to access it. If a site restricts project visibility to administrators only, non-admin users will receive a 403 Forbidden response.

Project Overview

GET /project/{project_id}/overview

Returns a project overview, containing various statistics and information about the project. The level of detail in the response depends on the user's permissions.

Path Parameters

Parameter Type Required Description
project_id string Yes Project ID for which to retrieve the overview

Response

Success Response (200 OK)

Project overview data in JSON format.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to access project overview (administrator access required)
  • 404 Not Found: Project with the specified ID does not exist

Note: For site administrators, the response will contain detailed information about costs, invoices, and other financial data. For non-site administrators who are project administrators, the response will contain limited information, including user and reservation counts.

Get Project Users

GET /project/{project_id}/users

Returns a list of project users.

Path Parameters

Parameter Type Required Description
project_id string Yes Project ID

Query Parameters

Parameter Type Description
limit integer Limits the number of results returned
offset integer Offset for pagination
role string Filter by role
include_site_role boolean Include site role in response
search string Search for users by display name
sort_atr string Sort attribute (e.g., "name")
sort_ord string Sort order ("asc" or "desc")

Response

Success Response (200 OK)

An array of user objects.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to view project users
  • 404 Not Found: Project with the specified ID does not exist

Get Project Site User Groups

GET /project/{project_id}/usergroups

Retrieves a list of user groups associated with the specified project's site.

Path Parameters

Parameter Type Required Description
project_id string Yes ID of the project for which to retrieve site user groups

Response

Success Response (200 OK)

A dictionary of user group data in JSON format.

Error Responses

  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to access this project's site user groups
  • 404 Not Found: Project with the specified ID does not exist

Get Project Events

GET /project/{project_id}/events

Returns the last n recent events for a specified project.

Path Parameters

Parameter Type Required Description
project_id string Yes The ID of the project for which to retrieve events

Query Parameters

Parameter Type Default Description
limit integer 5 The number of events to return
offset integer 0 The offset from which to start retrieving events
sort_ord string The sorting order either asc or desc

Response

Success Response (200 OK)

{
  "data": [
    // Array of event objects
  ],
  "numitems": 42  // Total number of events
}

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to view project events
  • 404 Not Found: Project with the specified ID does not exist

User's Project Reservations

GET /user/projects/reservation

Fetches all the projects ever used by the authenticated user in a reservation, returning only the project ID and name.

Response

Success Response (200 OK)

A list of project objects in JSON format, each containing name and project_id.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed

Note: The response will contain all projects that the authenticated user has ever used in a reservation, which can be used to populate a filter for history views.

Get Project Tags

GET /projects/tags

Returns a list of site-specific project tags.

Query Parameters

Parameter Type Description
site_id string Site ID
user_id string User ID. Must match the authenticated user's ID if specified
portal_id string Portal ID
exclude array List of tag IDs to exclude
inject_tag_id integer Tag ID to inject into the response
limit integer Maximum number of tags to return
offset integer Offset for pagination
query string Search query for tags
tag_name string Name of the tag

Response

Success Response (200 OK)

A JSON array of tag data.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to access the requested tags
  • 404 Not Found: Site, portal, or user with the specified ID does not exist

POST Endpoints

Create Project

POST /projects/{site_id}/create

Creates a new project within the specified site.

Path Parameters

Parameter Type Required Description
site_id string Yes Site ID where the project will be created

Request Body

Field Type Required Description
name string Yes Project name
description string No Project description
status string No Project status (one of: active, canceled, completed, delayed, inactive, needs_changes, preliminary)

Response

Success Response (200 OK)

The newly created project data in JSON format.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to create projects on this site
  • 404 Not Found: Site with the specified ID does not exist

Modify Project

POST /projects/modify

Modifies a project's details.

Request Body

Field Type Required Description
project_id string Yes Project ID
active boolean No Whether the project is active or not
name string No Project name
description string No Project description
status string No Project status (one of: active, inactive)
status_details string No Additional project status details
user_add_email_message string No Email message sent to users when added to the project
hidden_note string No Hidden note for site administrators (requires moderator permission)

Response

Success Response (200 OK)

The updated project data in JSON format.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to modify this project
  • 404 Not Found: Project with the specified ID does not exist

Set Project Users

POST /projects/setusers

Adds, modifies, or removes users from a project.

Request Body

The request body is an array of objects, each with the following fields:

Field Type Required Description
email string No* User email address (requires site admin permission)
project_id string Yes Project ID
role string No** Role of the user in the project (one of: user, admin)
user_id string No* User ID
usergroup_id integer No User group ID (requires site admin permission)
modify boolean No** Whether to modify the user's role
delete boolean No** Whether to delete the user from the project

* Either email or user_id is required.

** One of role (for add or modify), modify, or delete is required.

Response

Success Response (200 OK)

Users added, modified, or removed successfully.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to add, modify, or remove users from this project

Create or Modify Project Note

POST /projects/{project_id}/note

Creates a new project note or modifies an existing one.

Path Parameters

Parameter Type Required Description
project_id string Yes Project ID where the note will be created or modified

Request Body

Field Type Required Description
active boolean No Whether the note is active
note string No Note text
project_note_id string No Existing project note ID to modify
send_email boolean No Whether to send an email notification
subject string No Email subject line

Response

Success Response (200 OK)

The updated project note data in JSON format.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to create or modify notes for this project

Create Project Tag

POST /projects/tags

Creates a new site-specific tag for the specified site, named according to the "name" parameter.

Request Body

Field Type Required Description
site_id string No* Site ID
user_id string No* User ID
portal_id string No* Portal ID
project_tag_id string No** Project tag ID
name string Yes** Tag name
color string No Tag color
public boolean No Public flag
delete boolean No Delete flag

* One of site_id, user_id, or portal_id is required.

** name is required if creating a new tag. project_tag_id is required if updating an existing tag.

Response

Success Response (200 OK)

The tag data in JSON format.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to create tags on this site or portal
  • 404 Not Found: Site, user, or portal with the specified ID does not exist
POST /projects/{project_id}/tag/{action}

Links or unlinks a tag with a project. This endpoint supports site and user tags, as well as portal tags.

Path Parameters

Parameter Type Required Description
project_id string Yes Project ID where the tag will be linked or unlinked
action string Yes Action to perform, either "link" or "unlink"

Request Body

Field Type Required Description
site_id string No Site ID
portal_id string No Portal ID
user_id string No User ID
project_tag_id string No* Project tag ID
project_tag_ids array of strings No* List of project tag IDs

* Either project_tag_id or project_tag_ids is required.

Response

Success Response (200 OK)

Tag successfully linked or unlinked.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to link or unlink tags for this project

Pin or Unpin a Reservation in a Project

POST /projects/{project_string_id}/reservation/{reservation_string_id}/{action}

Pins or unpins a reservation within a project.

Path Parameters

Parameter Type Required Description
project_string_id string Yes Project string ID where the reservation will be pinned or unpinned
reservation_string_id string Yes Reservation string ID that will be pinned or unpinned
action string Yes The action to perform, either "pin" or "unpin"

Request Body

Empty JSON object {}

Response

Success Response (200 OK)

The updated project data in JSON format.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to pin or unpin reservations in this project
  • 404 Not Found: Project with the specified ID does not exist

Toggle Email Digests for Project

POST /projects/{project_id}/emails

Toggles email digests on or off for a specific project.

Path Parameters

Parameter Type Required Description
project_id string Yes Project ID for which to toggle email digests

Request Body

Field Type Required Description
value boolean Yes Whether to enable or disable email digests

Response

Success Response (200 OK)

The updated project data in JSON format.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to toggle email digests for this project
  • 404 Not Found: Project with the specified ID does not exist