REST API reference for Pixel Studio.
- Development:
http://localhost:5173 - Production:
https://your-domain.com
Most endpoints require authentication. The API uses session-based authentication via Google OAuth (legacy) or Supabase (v2). Both stacks land in the same User record.
- Redirect user to
/auth/google(or/auth/v2/googlefor the Supabase flow) - User authenticates with Google
- Callback to
/auth/google/callback(or/auth/v2/callback-google) - Session cookie is set
Protected endpoints return 401 Unauthorized if not authenticated.
47 REST endpoints under /api/* plus the /webhook Stripe handler. Detailed below — quick map:
| Family | Routes |
|---|---|
| Images | api.images.$imageId.like, .remix, .tags, .comments, .comments.$commentId.like, .delete |
| Videos | api.videos.$videoId.like, .comments, .comments.$commentId.like |
| Collections | api.collections (CRUD), .add-image, .remove-image, .check-image, .$collectionId.premium |
| Queue / Processing | api.queue.process-image, api.queue.status, api.processing.$requestId |
| Notifications | api.notifications (list, read, delete) |
| Users | api.users.$userId.follow, .followers, .following, api.user.images |
| User Analytics | api.user.analytics.dashboard, .style-fingerprint |
| Marketplace | api.marketplace.prompts (list), .purchase |
| Tips / Achievements | api.tips.send, api.achievements, api.streaks |
| Trending | api.trending |
| Print on Demand | api.print.products, .orders, .calculate |
| Admin | api.admin.images, api.admin.users.$userId.credits |
| Cache | api.cache.clear (admin) |
| User Preferences | api.preferences.theme (writes User.theme) |
| Webhooks | /webhook (Stripe) |
GET /api/collections
Returns all collections for the authenticated user.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
imageId |
string | Optional. Check if image exists in collections |
Response:
{
"collections": [
{
"id": "clx123...",
"title": "My Collection",
"imageCount": 5,
"hasImage": true
}
]
}POST /api/collections
Request Body (FormData):
| Field | Type | Required | Description |
|---|---|---|---|
title |
string | Yes | Collection name |
Response:
{
"success": true,
"collection": {
"id": "clx123...",
"title": "New Collection"
}
}GET /api/collections/:collectionId
Response:
{
"collection": {
"id": "clx123...",
"title": "My Collection",
"description": "...",
"images": [...]
}
}PATCH /api/collections/:collectionId
Request Body (FormData):
| Field | Type | Description |
|---|---|---|
title |
string | New title |
description |
string | New description |
DELETE /api/collections/:collectionId
Response:
{
"success": true
}POST /api/collections/add-image
Request Body (FormData):
| Field | Type | Required |
|---|---|---|
imageId |
string | Yes |
collectionId |
string | Yes |
Response:
{
"success": true
}Errors:
400- Image already in collection404- Collection or image not found
POST /api/collections/remove-image
Request Body (FormData):
| Field | Type | Required |
|---|---|---|
imageId |
string | Yes |
collectionId |
string | Yes |
GET /api/collections/check-image?imageId=xxx
Check which collections contain a specific image.
POST /api/images/:imageId/like
Like an image.
Response:
{
"success": true
}DELETE /api/images/:imageId/like
Remove like from an image.
POST /api/images/:imageId/remix
Fork an image — creates a new generation request seeded from the source's prompt/model/settings. The resulting Image records its source via parentId for lineage tracking.
POST /api/images/:imageId/tags
Trigger AI-powered tag extraction for an image (writes ImageTag + ImageAttribute rows).
DELETE /api/images/:imageId/delete
Soft-delete an image. Admin deletions are recorded to ImageDeletionLog for audit.
Mirrors the Images API but for Video records. Created via the create-video flow (Runway / Luma / Stability).
POST /api/videos/:videoId/like
DELETE /api/videos/:videoId/like
POST /api/videos/:videoId/comments
PATCH /api/videos/:videoId/comments/:commentId
DELETE /api/videos/:videoId/comments/:commentId
POST /api/videos/:videoId/comments/:commentId/like
DELETE /api/videos/:videoId/comments/:commentId/like
Same request/response shape as the equivalent image comment endpoints — see the Comments section above.
POST /api/images/:imageId/comments
Request Body (FormData):
| Field | Type | Required | Description |
|---|---|---|---|
comment |
string | Yes | Comment text |
Response:
{
"success": true,
"comment": {
"id": "clx123...",
"message": "Great image!",
"createdAt": "2024-01-01T00:00:00Z",
"user": {
"id": "...",
"name": "User Name",
"image": "..."
}
}
}PATCH /api/images/:imageId/comments/:commentId
Request Body (FormData):
| Field | Type | Required |
|---|---|---|
comment |
string | Yes |
DELETE /api/images/:imageId/comments/:commentId
POST /api/images/:imageId/comments/:commentId/like
DELETE /api/images/:imageId/comments/:commentId/like
POST /api/users/:userId/follow
Follow a user.
Response:
{
"success": true
}Errors:
400- Cannot follow yourself
DELETE /api/users/:userId/follow
GET /api/users/:userId/followers
Response:
{
"followers": [
{
"id": "...",
"name": "User Name",
"username": "username",
"image": "..."
}
]
}GET /api/users/:userId/following
Response:
{
"following": [
{
"id": "...",
"name": "User Name",
"username": "username",
"image": "..."
}
]
}GET /api/user/images?page=1&limit=20
Authenticated user's own images, paginated.
GET /api/user/analytics/dashboard
Returns the data backing /user/analytics — generation counts, credit spend, top models, engagement trends.
GET /api/user/analytics/style-fingerprint
Returns the user's StyleFingerprint — aggregated color / style / mood preferences derived from ImageTag + ImageAttribute.
GET /api/notifications
Response:
{
"notifications": [
{
"id": "...",
"type": "image_liked",
"read": false,
"createdAt": "2026-06-06T00:00:00Z",
"actor": { "id": "...", "name": "..." },
"subject": { "type": "image", "id": "..." }
}
],
"unreadCount": 4
}12 notification types supported (likes, comments, follows, tips, achievements, marketplace activity, etc.).
POST /api/notifications/read
Body: { "ids": ["..."] } or { "all": true }.
DELETE /api/notifications/:id
GET /api/marketplace/prompts?sort=trending&category=...
Response:
{
"prompts": [
{
"id": "...",
"title": "...",
"priceCredits": 25,
"creator": { "id": "...", "name": "..." },
"rating": 4.7,
"reviewCount": 12
}
]
}POST /api/marketplace/prompts/:promptId/purchase
Deducts credits, creates a PromptPurchase, and credits the creator's CreatorEarnings.
POST /api/tips/send
Body:
| Field | Type | Required |
|---|---|---|
recipientId |
string | Yes |
amount |
number (credits) | Yes |
message |
string | No |
imageId |
string | No (optional context) |
Creates a Tip row and a corresponding CreditTransaction on both sides.
GET /api/achievements # user's achievements + progress
GET /api/streaks # login-streak state
GET /api/trending?type=images|videos|prompts&window=24h|7d
Returns ranked content from the trending.server.ts computation (cached in Redis).
GET /api/print/products # available print products & sizes
POST /api/print/calculate # body: { imageId, productId } → { priceUsd }
POST /api/print/orders # creates a PrintOrder (Stripe checkout)
All admin endpoints require the caller's User.isAdmin = true. Listed routes under /api/admin/*:
GET /api/admin/images # paginated list with filters
POST /api/admin/users/:userId/credits # adjust balance, creates CreditTransaction
The admin UI (under /admin/*) calls these via Remix actions; treat them as internal-but-stable.
POST /api/preferences/theme
Body: { "theme": "light" | "dark" }
Persists the choice on User.theme. The client applies data-theme instantly via ThemeToggle.
POST /api/cache/clear
Admin-only. Invalidates the Redis cache keys listed in CACHING_STRATEGY.md.
GET /api/processing/:requestId
Get the status of an image generation request.
Response:
{
"status": "processing",
"progress": 50,
"message": "Generating images...",
"timestamp": "2024-01-01T00:00:00Z"
}Status Values:
| Status | Description |
|---|---|
queued |
Request is in queue |
processing |
Currently generating |
complete |
Generation finished |
failed |
Generation failed |
GET /api/queue/status
Get overall queue health and statistics.
POST /api/queue/process-image
Internal endpoint called by QStash to process queued jobs. Requires QStash signature verification.
POST /webhook
Handles Stripe payment events. Requires Stripe signature verification.
Handled Events:
checkout.session.completed- Process successful paymentcustomer.subscription.updated- Update subscription statuscustomer.subscription.deleted- Handle cancellation
GET /auth/google
Initiates Google OAuth flow.
GET /auth/google/callback
Handles OAuth callback from Google.
POST /auth/logout
Destroys the session and logs out the user.
All endpoints return consistent error responses:
{
"success": false,
"error": "Error message here"
}| Code | Description |
|---|---|
200 |
Success |
400 |
Bad Request - Invalid input |
401 |
Unauthorized - Not logged in |
403 |
Forbidden - No permission |
404 |
Not Found |
405 |
Method Not Allowed |
500 |
Internal Server Error |
Rate limiting is configured via environment variables:
RATE_LIMIT_MAX="100" # Max requests
RATE_LIMIT_WINDOW_MS="900000" # 15 minute windowWhen rate limited, the API returns:
{
"error": "Too many requests. Please try again later."
}For real-time processing updates, connect to the WebSocket server:
const ws = new WebSocket("ws://localhost:3001");
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
// { requestId, status, progress, message }
};
// Subscribe to a request
ws.send(
JSON.stringify({
type: "subscribe",
requestId: "request-id-here",
}),
);Processing Update:
{
"type": "processing_update",
"requestId": "...",
"status": "processing",
"progress": 50,
"message": "Generating..."
}Completion:
{
"type": "processing_update",
"requestId": "...",
"status": "complete",
"progress": 100,
"setId": "...",
"images": [...]
}List collections:
curl -X GET http://localhost:5173/api/collections \
-H "Cookie: session=..."Create collection:
curl -X POST http://localhost:5173/api/collections \
-H "Cookie: session=..." \
-F "title=My New Collection"Like an image:
curl -X POST http://localhost:5173/api/images/IMAGE_ID/like \
-H "Cookie: session=..."Follow a user:
curl -X POST http://localhost:5173/api/users/USER_ID/follow \
-H "Cookie: session=..."// List collections
const response = await fetch("/api/collections", {
credentials: "include",
});
const data = await response.json();
// Create collection
const formData = new FormData();
formData.append("title", "My Collection");
await fetch("/api/collections", {
method: "POST",
body: formData,
credentials: "include",
});
// Like an image
await fetch(`/api/images/${imageId}/like`, {
method: "POST",
credentials: "include",
});