Documentation Index
Fetch the complete documentation index at: https://mintlify.com/joaomonteir0/printheritage/llms.txt
Use this file to discover all available pages before exploring further.
PrintHeritage exposes a FastAPI-powered REST API that serves as the single backend entry point for the web application. All client interactions — from authenticating users and managing monitoring projects to uploading sensor datasets and handling team invitations — flow through this API. The sections below describe base connectivity, authentication conventions, CORS policy, and a complete endpoint reference organized by functional group.
Base URL
The API runs on port 8001 by default. The frontend resolves this address from the REACT_APP_API_URL environment variable at build time.
When deploying to a remote server, set REACT_APP_API_URL to the public address of your API host before building the frontend (e.g. https://api.printheritage.example.com).
Interactive API Docs
Because the backend is built with FastAPI, a fully interactive OpenAPI UI is automatically generated and available at:
http://localhost:8001/docs
http://localhost:8001/openapi.json.
Authentication
PrintHeritage uses the OAuth2 password flow to issue JWT Bearer tokens. Submit credentials once to /login; every subsequent request must carry the returned token in the Authorization header.
| Step | Detail |
|---|
| Token endpoint | POST /login |
| Request content type | application/x-www-form-urlencoded (OAuth2PasswordRequestForm) |
| Response | { "access_token": "...", "token_type": "bearer" } |
| Header for protected endpoints | Authorization: Bearer <access_token> |
| Token lifetime | 60 minutes (ACCESS_TOKEN_EXPIRE_MINUTES) |
| Signing algorithm | HS256 |
Tokens expire after 60 minutes. The client must re-authenticate by calling POST /login again. There is no refresh-token endpoint; store credentials securely to allow silent re-login.
Content Type
| Endpoint | Request Content-Type |
|---|
POST /login | application/x-www-form-urlencoded |
| All other endpoints | application/json |
application/json.
CORS Policy
The API is configured with permissive CORS settings suitable for local and staging environments:
CORSMiddleware(
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
For production deployments, restrict allow_origins to your known frontend domain(s) to prevent unauthorized cross-origin access.
Role Hierarchy
Access to certain endpoints depends on the authenticated user’s global_role. Roles are ordered from most to least privileged:
| Role | Value |
|---|
| Super Admin | SUPER_ADMIN |
| General Admin | GENERAL_ADMIN |
| Project Admin | PROJECT_ADMIN |
| Visualizer | VISUALIZER |
SUPER_ADMIN bypasses all role checks. GENERAL_ADMIN has implicit access to all projects. PROJECT_ADMIN can manage datasets and members within projects they belong to. VISUALIZER has read-only project access.
Endpoint Reference
All endpoints except POST /login and POST /register require a valid Authorization: Bearer <token> header. The Min Role column shows the minimum global_role required; endpoints that only check project membership rather than a global role are marked as Any (member).
Autenticação
| Method | Path | Auth Required | Min Role |
|---|
POST | /login | No | — |
POST | /register | No | — |
GET | /me | Yes | Any |
POST | /change-password | Yes | Any |
Utilizadores
| Method | Path | Auth Required | Min Role |
|---|
GET | /users | Yes | GENERAL_ADMIN |
PATCH | /users/{user_id} | Yes | Any |
DELETE | /users/{user_id} | Yes | Any |
GET | /users/search | Yes | Any |
GET | /users/{user_id}/profile | Yes | Any |
GET /users accepts an optional ?q= query parameter to filter results by email or full name. GET /users/search requires a minimum of 3 characters in the q parameter and searches by email only.
Projetos
| Method | Path | Auth Required | Min Role |
|---|
POST | /projects | Yes | Any |
GET | /projects | Yes | Any |
GET | /projects/{project_id} | Yes | Any (member) |
PATCH | /projects/{project_id}/data | Yes | Any (member) |
DELETE | /projects/{project_id}/datasets/{dataset_id} | Yes | PROJECT_ADMIN |
GET | /projects/{project_id}/members | Yes | Any (member) |
DELETE | /projects/{project_id}/members/{user_id} | Yes | Any (member) |
PATCH | /projects/{project_id}/favorite | Yes | Any |
SUPER_ADMIN and GENERAL_ADMIN users have implicit access to all projects regardless of membership. All other roles must have an ACCEPTED permission entry for the project.
Convites
| Method | Path | Auth Required | Min Role |
|---|
GET | /invitations | Yes | Any |
POST | /invitations/{id}/accept | Yes | Any |
POST | /invitations/{id}/reject | Yes | Any |
POST | /invitations/{id}/read | Yes | Any |
POST | /projects/{project_id}/invite | Yes | Any (member) |
Auditoria
| Method | Path | Auth Required | Min Role |
|---|
GET | /audit-logs | Yes | SUPER_ADMIN |
The audit log records all significant actions — user creation, login, project creation, dataset uploads, invitations, and password changes. Only SUPER_ADMIN accounts can retrieve the full log. Results are returned in reverse-chronological order.