By name: api-endpoints description: Reference for all onepixel API endpoints, their HTTP methods, paths, auth requirements, and behavior.
API Endpoints Skill
Use this skill when adding, modifying, or debugging API routes, middleware, or authentication logic.
Authentication types
Four auth middleware are defined in src/security/middlewares.go:
- MandatoryAdminApiKeyAuthMiddleware – requires
X-API-Keyheader matchingconfig.AdminApiKey. Setsadmin=truein Fiber locals. - OptionalAdminApiKeyAuthMiddleware – same check, but proceeds without error if header is absent.
- MandatoryJwtAuthMiddleware – requires
Authorization: Bearer <token>. Stores decoded*models.Userin Fiber locals. - OptionalJwtAuthMiddleware – same check, but proceeds without error if header is absent.
Users endpoints (/api/v1/users)
Source: src/routes/api/users.go
| Method | Path | Auth | Description |
|---|---|---|---|
POST |
/users |
X-API-Key (required) | Register a new user. Returns JWT token. 409 if email exists. |
POST |
/users/login |
None | Login with email/password. Returns JWT token. 401 if invalid. |
GET |
/users/{userid} |
JWT (required) | Get user info (currently returns placeholder). |
PATCH |
/users/{userid} |
JWT (required) | Update user password. Returns updated user and new JWT token. |
URLs endpoints (/api/v1/urls)
Source: src/routes/api/urls.go
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/urls |
JWT (optional) + X-API-Key (optional) | Get all URLs. Admin can filter by ?userid=. Returns 401 if neither auth. |
GET |
/urls/groups |
JWT (required) | Get URL groups created by the authenticated user. |
POST |
/urls/groups |
X-API-Key (required) | Create a URL group. Requires short_path and creator_id. |
POST |
/urls/groups/{group}/shorten |
JWT (required) | Create a random short URL inside a group the user owns. |
POST |
/urls/groups/{group}/shorten/{shortcode} |
JWT (required) | Create a specific short URL inside a group the user owns. |
GET |
/urls/groups/{group}/{shortcode} |
None | Get URL info (long URL + hit count) for a grouped short URL. |
POST |
/urls |
JWT (required) | Create a random short URL for the authenticated user. |
PUT |
/urls/{shortcode} |
JWT (required) | Create a short URL with a specific shortcode. 409 if exists, 403 if forbidden. |
GET |
/urls/{shortcode} |
None | Get URL info (long URL + hit count). 404 if not found. |
Stats endpoints (/api/v1/stats)
Source: src/routes/api/stats.go
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/stats |
JWT (optional) | Get redirect statistics for the authenticated user. |
GET |
/stats/{shortcode} |
None | Get stats for a specific short URL (currently returns placeholder). |
Redirect endpoints (Main app – MAIN_SITE_HOST)
Source: src/routes/redirect/redirect.go, src/server/server.go
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/{group}/{shortcode} |
None | Redirect to the long URL via group + shortcode. Logs event async. |
GET |
/{shortcode} |
None | Redirect to the long URL via shortcode. Logs event async. |
GET |
/ |
None | Redirect to admin host. Logs event async. |
Static and documentation (Admin app)
Source: src/server/server.go
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/docs/* |
None | Swagger UI for OpenAPI documentation. |
GET |
/ |
None | Static files from ./public_html (gzip, 1-hour cache). |
X-API-Key summary
Only these endpoints require or accept the X-API-Key header:
POST /api/v1/users– required (admin-only user registration)POST /api/v1/urls/groups– required (admin-only group creation)GET /api/v1/urls– optional (admin access to query any user's URLs)