API reference
Every HTTP endpoint, its auth requirement and what it does.
The live, interactive schema is generated by FastAPI at /docs (Swagger UI) and /openapi.json on the API host. This page is the curated summary.
Base URL: https://api.vod.spokhrel.dev in production, http://localhost locally (through Caddy).
Auth: Authorization: Bearer <access_token> unless stated otherwise. Errors use FastAPI's standard shape, { "detail": "…" }, or a list of validation errors for 422.
| Auth label | Meaning |
|---|---|
| Public | No token needed |
| Optional | Works without a token; a valid token can unlock more (for example, your own private video) |
| User | Any valid access token |
| Verified | Valid token and verified email |
| Admin | Valid token and ADMIN role |
Auth
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /auth/signup | Public | Create an account and send a verification email |
| GET | /auth/verify-email?token= | Public | Verify the email address |
| POST | /auth/resend-verification | Public | Send a new verification link (3 per hour) |
| POST | /auth/signin | Public | Returns access_token, refresh_token and the user |
| POST | /auth/refresh | Refresh token in body | Returns a new access token |
| POST | /auth/logout | Refresh token in body | Revoke the refresh token |
| POST | /auth/forgot-password | Public | Email a 6-digit reset code |
| POST | /auth/reset-password | Public | Set a new password with the code; signs out every session |
User
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /user/profile | Verified | The current user |
Videos
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /videos/ | Public | Public feed (skip, limit) |
| GET | /videos/by-id/{id} | Optional | One video; private ones only for owner or admin |
| GET | /videos/user/me | User | Your own videos |
| GET | /videos/{id}/status | User (owner) | Processing status and progress |
| POST | /videos/{id}/view | Optional | Increment the view count |
| GET | /videos/list-all | Admin | Admin list: search, filters, sorting, pagination with total |
| POST | /videos/create | Admin | Legacy multipart upload (video, thumbnail, data JSON string) |
| PATCH | /videos/by-id/{id} | Admin | Partial metadata update |
| PATCH | /videos/by-id/{id}/visibility | Admin | Set is_public |
| POST | /videos/{id}/thumbnail | Admin | Upload and attach a poster |
| GET | /videos/by-id/{id}/download-url | Admin | 15-minute presigned download URL for the original |
| DELETE | /videos/by-id/{id} | Admin | Soft delete |
Uploads (tus)
| Method | Path | Auth | Description |
|---|---|---|---|
| POST, PATCH, HEAD | /files/… | Token in tus metadata | The tus protocol itself, served by tusd, not FastAPI |
| GET | /internal/tus/hooks/uploads/{upload_id} | Admin | { status, video_id } for a finished upload |
tusd's own hook endpoint is internal to the Docker network and not part of the public API.
Health
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /health/ | Public | { "status": "Ok!" } (process liveness only; it does not check the database or Redis) |
Example: sign in, then call an admin endpoint
TOKEN=$(curl -s -X POST https://api.vod.spokhrel.dev/auth/signin \
-H 'Content-Type: application/json' \
-d '{"email":"admin@example.com","password":"…"}' | jq -r .access_token)
curl -s "https://api.vod.spokhrel.dev/videos/list-all?limit=10&processing_status=failed" \
-H "Authorization: Bearer $TOKEN"