Backend API Routes

Backend API Routes

Base URLs

• Local API base: http://localhost:8000
• OpenAPI schema: GET /openapi.json
• Swagger UI: GET /docs
• ReDoc: GET /redoc
• Health/root message: GET /

Authentication Rules

get_current_user checks token in this order:

1. Query parameter ?token=...
2. HttpOnly cookie access_token
3. Header Authorization: Bearer <token>

Route Table

Method	Path	Auth	Handler / Notes
GET	/	Public	Root welcome message (main.py).

Auth (backend/src/stemhub/auth.py, prefix /auth)

Method	Path	Auth	Description
GET	/auth/login/google	Public	Start Google OAuth flow (sets oauth_state cookie and redirects to Google).
GET	/auth/callback/google	Public	OAuth callback: exchanges code, upserts user, sets access_token cookie, redirects frontend callback.
POST	/auth/register	Public	Create user account and set access_token cookie.
POST	/auth/swagger-login	Public	Swagger password login endpoint (email passed as OAuth username).
POST	/auth/login	Public	Email/password login and set access_token cookie.
POST	/auth/logout	Public	Delete access_token cookie.
GET	/auth/me	Auth required	Return current authenticated user profile.
PUT	/auth/me	Auth required	Update current user profile fields.

Projects (backend/src/stemhub/routers/projects.py, prefix /projects)

Method	Path	Auth	Description
POST	/projects/	Auth required	Create project for current user; auto-creates main branch.
GET	/projects/	Auth required	List projects where user is owner or collaborator.
GET	/projects/{project_id}/summary	Auth required	Get project summary (project details, branches, recent versions, preview state).
POST	/projects/{project_id}/preview	Auth required	Upload project preview audio (.wav/.mp3/.ogg/.flac).
GET	/projects/{project_id}/preview	Auth required	Download project preview audio.
DELETE	/projects/{project_id}/preview	Auth required	Delete project preview audio.
PUT	/projects/{project_id}	Auth required	Update project metadata (owner only).
DELETE	/projects/{project_id}	Auth required	Soft-delete project (owner only).

Branches (backend/src/stemhub/routers/branches.py)

Method	Path	Auth	Description
POST	/projects/{project_id}/branches/	Auth required	Create branch in project (owner only).
GET	/projects/{project_id}/branches/	Auth required	List non-deleted branches for project (owner/collaborator).
GET	/branches/{branch_id}	Auth required	Get branch by id if accessible.
PUT	/branches/{branch_id}	Auth required	Update branch (owner only).
DELETE	/branches/{branch_id}	Auth required	Soft-delete branch (owner only).

Versions (backend/src/stemhub/routers/versions.py)

Method	Path	Auth	Description
POST	/branches/{branch_id}/versions/	Auth required	Create version/commit on branch.
GET	/branches/{branch_id}/versions/	Auth required	List non-deleted versions for branch.
GET	/versions/{version_id}	Auth required	Get single version by id if accessible.
DELETE	/versions/{version_id}	Auth required	Soft-delete version (owner only).

Files / Artifacts (backend/src/stemhub/routers/files.py)

Method	Path	Auth	Description
POST	/versions/{version_id}/artifact	Auth required	Upload artifact file for version (one-time; rejects if already present).
GET	/versions/{version_id}/artifact	Auth required	Download version artifact binary.

Collaborators (backend/src/stemhub/routers/collaborators.py)

Method	Path	Auth	Description
POST	/projects/{project_id}/collaborators/	Auth required	Add collaborator by username (owner only).
GET	/projects/{project_id}/collaborators/	Auth required	List collaborators (owner or collaborator).
DELETE	/projects/{project_id}/collaborators/{user_id}	Auth required	Remove collaborator (owner only).

Stats (backend/src/stemhub/routers/stats.py)

Method	Path	Auth	Description
GET	/projects/{project_id}/stats/activity	Auth required	26-week daily activity + totals.
GET	/projects/{project_id}/stats/top-contributors	Auth required	Contributors ranked by commit count.

Storage-Related Endpoints

Endpoints that read/write storage provider (localfs or gcs):

• POST /versions/{version_id}/artifact
• GET /versions/{version_id}/artifact
• POST /projects/{project_id}/preview
• GET /projects/{project_id}/preview
• DELETE /projects/{project_id}/preview

Source of Truth Files

• backend/src/stemhub/main.py
• backend/src/stemhub/auth.py
• backend/src/stemhub/routers/projects.py
• backend/src/stemhub/routers/branches.py
• backend/src/stemhub/routers/versions.py
• backend/src/stemhub/routers/files.py
• backend/src/stemhub/routers/collaborators.py
• backend/src/stemhub/routers/stats.py