Overview
The Weggle REST API provides programmatic access to all platform features. All responses are JSON. All requests must be made over HTTPS in production.
// Success { "success": true, "data": { ... } } // Error { "success": false, "error": "message" }
Authentication
The API supports two authentication methods. Most programmatic access should use an API Key.
Generate a key at /settings/api-keys. Pass it in the X-API-Key header on every request.
X-API-Key: wk_your_key_here
Log in via POST /v1/auth/login — a session cookie is set automatically. Best for browser-based integrations.
Cookie: weggle.session_token=...
wk_. Manage at /settings/api-keys.
Errors
| Code | Meaning |
|---|---|
| 200 | OK — request succeeded |
| 201 | Created — resource created successfully |
| 400 | Bad Request — missing or invalid parameters |
| 401 | Unauthorized — authentication required or token invalid |
| 403 | Forbidden — authenticated but lacks permission |
| 404 | Not Found — resource does not exist |
| 422 | Unprocessable — validation error (see details array) |
| 429 | Too Many Requests — rate limit exceeded |
| 500 | Internal Server Error — something went wrong on our end |
Rate Limiting
Rate limits are enforced per IP address. Responses include rate limit headers:
RateLimit-Limit: 100 RateLimit-Remaining: 87 RateLimit-Reset: 1748192400
Auth
/v1/auth/login
Authenticate with email and password. Sets a session cookie.
{ "email": "user@example.com", "password": "secret" }{ "success": true, "user": { "id": "...", "username": "alice", "role": "user" } }/v1/auth/register
Create a new account.
{ "username": "alice", "email": "user@example.com", "password": "secret" }{ "success": true, "user": { "id": "...", "username": "alice" } }/v1/auth/logout
Invalidate the current session.
{ "success": true }Users
/v1/users/me
Returns the authenticated user's full profile. Requires authentication.
{ "success": true, "user": { "id": "...", "username": "alice", "email": "...", "role": "user", "plan": "free", "storage_used": 0 } }/v1/users/profile
Get a user's public profile by username or ID.
username optional — username to look upuserId optional — user ID to look up{ "success": true, "profile": { "username": "alice", "bio": "...", "avatar_url": "..." } }/v1/users/profile
Update the authenticated user's profile fields.
{ "bio": "My new bio", "display_username": "Alice" }{ "success": true, "user": { ... } }/v1/users/avatar
Upload a new profile avatar. Multipart form-data.
Content-Type: multipart/form-data field: avatar (image file, max 5MB)
{ "success": true, "avatarUrl": "https://cdn.weggle.xyz/..." }/v1/users/search
Search users by username.
q required — search query (min 2 chars)limit optional — max results (default 10){ "success": true, "users": [{ "username": "alice", "avatar_url": "..." }] }Files
/v1/files
Returns the authenticated user's uploaded files. Requires X-API-Key.
limit optional — max results (default 25, max 100)offset optional — pagination offset (default 0)search optional — filename searchtype optional — mime type prefix e.g. image/publicStatus optional — true / false{ "success": true, "data": { "files": [{ "id": 1, "filename": "photo.jpg", "originalName": "photo.jpg", "mimeType": "image/jpeg", "size": 102400, "humanReadableSize": "100 KB", "isPublic": false, "downloadCount": 0, "createdAt": "...", "url": "/file/1" }], "pagination": { "total": 42, "limit": 25, "offset": 0, "hasMore": true } } }/v1/files/:fileId
Returns metadata for a specific file. Private files require authentication as the owner.
fileId required — integer file ID in path{ "success": true, "data": { "file": { "id": 1, "filename": "photo.jpg", "mimeType": "image/jpeg", "size": 102400, "humanReadableSize": "100 KB", "isPublic": false, "downloadCount": 0, "createdAt": "...", "url": "/file/1" } } }/v1/files/upload
Upload a file. Multipart form-data. Max 50MB on Free plan.
Content-Type: multipart/form-data field: file (required, binary) field: isPublic (optional, boolean, default false)
{ "success": true, "file": { "id": 1, "url": "/file/1" } }/v1/files/:fileId
Update file metadata (filename, visibility).
fileId required — path parameter{ "filename": "new-name.jpg", "isPublic": true }{ "success": true, "file": { ... } }/v1/files/:fileId
Permanently delete a file.
fileId required — path parameter{ "success": true, "message": "File deleted" }Memes
/v1/memes
Returns the authenticated user's memes. Requires X-API-Key.
limit optional — max results (default 25, max 100)offset optionaltemplateId optional — filter by template{ "success": true, "data": { "memes": [{ "id": 1, "title": "My Meme", "templateId": "drake", "templateName": "Drake", "topText": "Writing docs", "bottomText": "Shipping bugs", "isPublic": true, "viewCount": 42, "createdAt": "...", "imageUrl": "/meme/1/view" }], "pagination": { "total": 5, "limit": 25, "offset": 0, "hasMore": false } } }/v1/memes
Create a new meme from a template. Requires X-API-Key with write:memes permission (or full-access key).
{ "templateId": "drake", "title": "My Meme", "textFields": ["top text", "bottom text"], "isPublic": true }{ "success": true, "meme": { "id": 1, "imageUrl": "/meme/1/view" } }/v1/memes/:memeId
Delete a meme you own.
memeId required{ "success": true }Social
/v1/friends
Returns all accepted friendships for the current user.
{ "success": true, "friends": [{ "id": "...", "username": "bob" }] }/v1/friends
Send a friend request to another user.
{ "addresseeId": 123 }{ "success": true, "friendship": { "status": "pending" } }/v1/friends/respond
Accept or decline a friend request.
{ "friendshipId": "...", "action": "accept" }{ "success": true }/v1/followers
Returns followers of the current user.
{ "success": true, "followers": [{ "username": "..." }], "total": 42 }/v1/follow
Follow another user.
{ "followingId": 123 }{ "success": true }Messages
/v1/messages/conversations
Get all conversations for the current user.
{ "success": true, "conversations": [{ "id": "...", "participant": { "username": "bob" }, "lastMessage": "Hey!" }] }/v1/messages/friend/:friendId
Get messages with a specific friend.
friendId required{ "success": true, "messages": [{ "id": "...", "content": "Hello!", "sender_id": "..." }] }/v1/messages/friend/:friendId
Send a direct message to a friend.
friendId required{ "content": "Hello!" }{ "success": true, "message": { "id": "..." } }Plans
/v1/plans
Returns all available subscription plans.
{ "success": true, "plans": [{ "id": "free", "name": "Free", "storage": 5368709120 }] }/v1/subscriptions/current
Returns the authenticated user's active subscription.
{ "success": true, "subscription": { "plan": "free", "storage_used": 0, "storage_limit": 5368709120 } }Wall
/wall
Fetch public wall posts.
page optional{ "success": true, "posts": [{ "id": "...", "content": "Hello world", "username": "alice" }] }/wall
Post a public message to the wall. Requires authentication.
{ "content": "Hello, world!" }{ "success": true, "post": { "id": "..." } }