HTTP API
Relevant source files
The following files were used as context for generating this wiki page:
The PuppyPad HTTP API provides programmatic access to member site management. It enables automated workflows such as deployment scripts, command-line tools, and GitHub Actions by allowing users to list, upload, and delete files outside of the browser-based dashboard.
Sources: README.md:32-35, src/views.js:527-529
Authentication and Security
The API uses a per-member API key for authentication. You generate this key on the /dashboard/api page. PuppyPad stores only the SHA256 fingerprint of the key, meaning the full key is displayed only once upon creation.
Authentication requires a Bearer token in the Authorization HTTP header. The API ignores session cookies and does not require CSRF tokens, preventing cross-site requests from using a visitor's browser session.
Sources: src/server.js:909-913, src/server.js:926-928, src/views.js:531-532
Security Constraints
- Password Dependency: Changing or resetting your account password automatically revokes and switches off the current API key.
- Verification: The API is only accessible to verified accounts that are not currently banned.
- Rate Limiting: The server restricts API requests to 120 per minute per member.
- Moderation: If a moderator takes a site down, API editing capabilities are disabled.
Sources: src/server.js:914-918, src/views.js:529-530, README.md:34-35
The diagram above illustrates the authentication flow for a standard API request. Sources: src/server.js:909-923
Public API Endpoints
All API endpoints return responses in JSON format.
Site Information
GET /api/site retrieves metadata about the member site, including usage statistics and limits.
| Field | Description |
|---|---|
name | The site subdomain/username. |
url | The public URL of the site. |
used_bytes | Total storage currently used. |
quota_bytes | Maximum storage allowed for the member. |
files | Current count of files on the site. |
max_files | Upper limit for the number of files (default 2000). |
bandwidth_today_bytes | Bandwidth consumed in the current UTC day. |
Sources: src/server.js:933-941, src/views.js:542-543
File Management
GET /api/files lists every file in the site directory with its size and last modified timestamp.
Sources: src/server.js:942-953, src/views.js:545-546
POST /api/upload accepts multipart form data to upload up to 20 files at once.
- Field Name:
files - Path Preservation: The API preserves folder structures if filenames include paths (e.g.,
pics/cat.png). - Validation: Files must match the
ALLOWED_EXTallowlist and stay within the member's storage quota and theMAX_FILE_MBper-file limit.
Sources: src/server.js:954-968, src/util.js:46-47, src/views.js:548-549
POST /api/delete removes a specific file.
- Body Parameter:
path(e.g.,pics/cat.png) - Behavior: Successfully deleting the last file in a folder also removes the empty parent directories.
Sources: src/server.js:969-975, src/views.js:551-552
Internal Screenshot API
A separate screenshot worker uses an internal API to generate site previews. These routes are protected by a SHOT_TOKEN and are typically only reachable within the internal Docker network.
| Endpoint | Method | Description |
|---|---|---|
/internal/shots/next | GET | Returns the next site name and URL needing a screenshot. |
/internal/shots/:name | POST | Receives raw JPEG data for a specific site screenshot. |
Sources: src/server.js:379-383, src/server.js:384-388, PLAN.md:14-20
The flowchart above shows the validation logic applied to file uploads through the API. Sources: src/server.js:956-967, src/util.js:51-60
Error Handling
The API uses standard HTTP status codes to indicate the result of a request.
- 400 Bad Request: The request body was malformed, or files failed validation (e.g., prohibited file type).
- 401 Unauthorized: Missing or unknown API key.
- 403 Forbidden: The site is banned or the API key was invalidated during the request.
- 404 Not Found: The requested endpoint or file does not exist.
- 429 Too Many Requests: The member exceeded the rate limit of 120 requests per minute.
- 503 Service Unavailable: The server is short on disk space for new uploads.
Sources: src/server.js:154-158, src/server.js:914-921, src/server.js:976-981
Conclusion
The PuppyPad HTTP API provides a robust interface for headless site management while maintaining strict security through password-linked keys and internal network isolation for administrative tasks. It enforces the same content and storage rules as the web dashboard to ensure consistency and prevent abuse.
Sources: PLAN.md:112-114, README.md:32-35