Project Management Endpoints — CRUD and Members

Projects are the core organisational unit in PrintHeritage, grouping sensor datasets and team members around a monitored heritage structure. Every project has an owner and a set of ProjectPermission records that control which users can access it. SUPER_ADMIN and GENERAL_ADMIN users see all projects by default; all other roles see only projects they have been explicitly granted ACCEPTED membership in. All write operations emit audit log entries.

POST /projects

Creates a new project. The authenticated user is automatically added as a member with ACCEPTED status and an access_level matching their global_role. A PROJECT_CREATE entry is written to the audit log on success. Authentication: Bearer token required. Content-Type: application/json

name

string

required

Human-readable name for the project. Must be non-empty.

description

string

Optional free-text description of the monitored structure or project scope.

Response — 200 OK — ProjectResponse

string (UUID)

Unique identifier of the newly created project.

name

string

Name of the project as provided.

description

string | null

Project description, or null if not provided.

owner_id

string (UUID)

UUID of the user who created the project.

datasets

array | null

List of sensor dataset objects attached to the project. Empty ([]) on creation.

created_at

string (datetime)

ISO 8601 timestamp of when the project was created.

Error responses

Status	Meaning
`401 Unauthorized`	Token is missing, expired, or invalid.

curl -X POST https://api.printheritage.com/projects \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aqueduct North Wing",
    "description": "Structural health monitoring for the north wing arcade."
  }'

{
  "id": "c9d8e7f6-1234-5678-abcd-000000000001",
  "name": "Aqueduct North Wing",
  "description": "Structural health monitoring for the north wing arcade.",
  "owner_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "datasets": [],
  "created_at": "2024-06-15T10:30:00"
}

GET /projects

Returns the list of projects visible to the authenticated user. SUPER_ADMIN and GENERAL_ADMIN users receive all projects via an outer join, meaning they see projects even without an explicit membership. All other roles see only projects where they hold an ACCEPTED ProjectPermission. Results are ordered by is_favorite DESC, then created_at DESC. An optional name search narrows results. Authentication: Bearer token required.

string

Optional case-insensitive name filter. Applies SQL ILIKE '%q%' to the project name column.

Response — 200 OK — List[dict] Each item is a ProjectResponse plus an is_favorite boolean.

string (UUID)

Unique identifier of the project.

name

string

Project name.

description

string | null

Project description.

owner_id

string (UUID)

UUID of the project owner.

datasets

array | null

List of dataset objects attached to this project.

created_at

string (datetime)

ISO 8601 creation timestamp.

is_favorite

boolean

Whether the authenticated user has marked this project as a favorite. false when no ProjectPermission record exists for admin users browsing projects they have not explicitly joined.

Error responses

Status	Meaning
`401 Unauthorized`	Token is missing, expired, or invalid.

curl -X GET "https://api.printheritage.com/projects?q=aqueduct" \
  -H "Authorization: Bearer <access_token>"

[
  {
    "id": "c9d8e7f6-1234-5678-abcd-000000000001",
    "name": "Aqueduct North Wing",
    "description": "Structural health monitoring for the north wing arcade.",
    "owner_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "datasets": [],
    "created_at": "2024-06-15T10:30:00",
    "is_favorite": true
  }
]

GET /projects/

Retrieves the full detail record for a single project. Access is validated via validate_project_access: SUPER_ADMIN and GENERAL_ADMIN users are permitted unconditionally; all other users must hold an ACCEPTED ProjectPermission for the requested project. Authentication: Bearer token required. Caller must have project access.

project_id

string (UUID)

required

UUID of the project to retrieve.

Response — 200 OK — ProjectResponse

string (UUID)

Unique identifier of the project.

name

string

Project name.

description

string | null

Project description.

owner_id

string (UUID)

UUID of the project owner.

datasets

array | null

List of sensor dataset objects attached to the project.

created_at

string (datetime)

ISO 8601 creation timestamp.

Error responses

Status	Meaning
`401 Unauthorized`	Token is missing, expired, or invalid.
`403 Forbidden`	Caller does not have `ACCEPTED` access to this project.

curl -X GET https://api.printheritage.com/projects/c9d8e7f6-1234-5678-abcd-000000000001 \
  -H "Authorization: Bearer <access_token>"

{
  "id": "c9d8e7f6-1234-5678-abcd-000000000001",
  "name": "Aqueduct North Wing",
  "description": "Structural health monitoring for the north wing arcade.",
  "owner_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "datasets": [],
  "created_at": "2024-06-15T10:30:00"
}

GET /projects//members

Lists all users who hold a ProjectPermission record for the given project, regardless of membership status. Access is validated with the same validate_project_access check used by other project-scoped endpoints. Authentication: Bearer token required. Caller must have project access.

project_id

string (UUID)

required

UUID of the project whose members should be listed.

Response — 200 OK — array of member objects

user_id

string (UUID)

Unique identifier of the member.

string

Email address of the member.

full_name

string | null

Display name of the member.

profile_pic_url

string | null

Profile picture URL of the member.

global_role

string

Platform-wide role of the member: SUPER_ADMIN, GENERAL_ADMIN, PROJECT_ADMIN, or VISUALIZER.

project_role

string

The access_level from the member’s ProjectPermission record, which mirrors global_role values.

status

string

Membership status: PENDING, ACCEPTED, or REJECTED.

Error responses

Status	Meaning
`401 Unauthorized`	Token is missing, expired, or invalid.
`403 Forbidden`	Caller does not have access to this project.

curl -X GET https://api.printheritage.com/projects/c9d8e7f6-1234-5678-abcd-000000000001/members \
  -H "Authorization: Bearer <access_token>"

[
  {
    "user_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "email": "jane@example.com",
    "full_name": "Jane Doe",
    "profile_pic_url": null,
    "global_role": "PROJECT_ADMIN",
    "project_role": "PROJECT_ADMIN",
    "status": "ACCEPTED"
  }
]

DELETE /projects//members/

Removes a user from a project by deleting their ProjectPermission record. The project owner cannot be removed — attempting to do so returns HTTP 400. On success, a PROJECT_MEMBER_REMOVE entry is written to the audit log. Authentication: Bearer token required.

The project owner’s membership cannot be removed. Attempting to delete the owner returns 400 Bad Request.

project_id

string (UUID)

required

UUID of the project from which the user should be removed.

user_id

string (UUID)

required

UUID of the user to remove. Must not be the project owner.

Response — 200 OK

boolean

Always true when the member was successfully removed.

Error responses

Status	Meaning
`400 Bad Request`	The target user is the project owner and cannot be removed.
`401 Unauthorized`	Token is missing, expired, or invalid.

curl -X DELETE \
  https://api.printheritage.com/projects/c9d8e7f6-1234-5678-abcd-000000000001/members/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer <access_token>"

{
  "ok": true
}

PATCH /projects//favorite

Toggles the is_favorite flag on the calling user’s ProjectPermission for the given project. If no permission record exists for the user (e.g. an admin who has never explicitly joined the project), a new ACCEPTED permission record is created with is_favorite set to true. Subsequent calls flip the flag between true and false. Authentication: Bearer token required.

project_id

string (UUID)

required

UUID of the project to toggle as a favorite.

Response — 200 OK

is_favorite

boolean

The new value of the is_favorite flag after the toggle. true means the project is now a favorite; false means it has been unfavorited.

Error responses

Status	Meaning
`401 Unauthorized`	Token is missing, expired, or invalid.

curl -X PATCH \
  https://api.printheritage.com/projects/c9d8e7f6-1234-5678-abcd-000000000001/favorite \
  -H "Authorization: Bearer <access_token>"

{
  "is_favorite": true
}

Overview

Endpoints

Project Management Endpoints — CRUD and Members

POST /projects

GET /projects

GET /projects/

GET /projects//members

DELETE /projects//members/

PATCH /projects//favorite

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /projects

​GET /projects

​GET /projects/

​GET /projects//members

​DELETE /projects//members/

​PATCH /projects//favorite

Build docs developers (and LLMs) love

POST /projects

GET /projects

GET /projects/

GET /projects//members

DELETE /projects//members/

PATCH /projects//favorite