342 lines
6.7 KiB
Markdown
342 lines
6.7 KiB
Markdown
# OnlyPrompt API
|
|
|
|
This file documents the backend endpoints used by the frontend. The backend is a helper service for server communication, authentication and shared data persistence.
|
|
|
|
Base URL in local Docker setup:
|
|
|
|
```text
|
|
http://localhost:1801
|
|
```
|
|
|
|
Authentication uses a `jwt` cookie set by the login endpoint. Protected endpoints require a logged-in user.
|
|
|
|
## Auth
|
|
|
|
### Register
|
|
|
|
```http
|
|
POST /api/v1/auth/register
|
|
Content-Type: application/json
|
|
```
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"displayName": "Isabelle",
|
|
"userName": "its_isabelle",
|
|
"email": "isabelle@test.com",
|
|
"password": "1234"
|
|
}
|
|
```
|
|
|
|
Response: created user data or validation errors.
|
|
|
|
### Login
|
|
|
|
```http
|
|
POST /api/v1/auth/login
|
|
Content-Type: application/json
|
|
```
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"userNameOrEmail": "isabelle@test.com",
|
|
"password": "1234"
|
|
}
|
|
```
|
|
|
|
Response: sets the auth cookie.
|
|
|
|
### Current User
|
|
|
|
```http
|
|
GET /api/v1/auth/me
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"id": "uuid",
|
|
"userName": "its_isabelle",
|
|
"email": "isabelle@test.com",
|
|
"roles": ["User"]
|
|
}
|
|
```
|
|
|
|
### Logout
|
|
|
|
```http
|
|
POST /api/v1/auth/logout
|
|
```
|
|
|
|
Deletes the auth cookie and redirects to login.
|
|
|
|
## Profiles
|
|
|
|
### Current Profile
|
|
|
|
```http
|
|
GET /api/v1/profiles/self
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"displayName": "Isabelle",
|
|
"slug": "its_isabelle",
|
|
"bio": "AI creator",
|
|
"avatarUrl": "data:image/png;base64,...",
|
|
"specialities": null,
|
|
"averageRating": 0,
|
|
"subscribers": 0
|
|
}
|
|
```
|
|
|
|
### Creator List
|
|
|
|
```http
|
|
GET /api/v1/profiles?sort=popular&limit=50&search=belle
|
|
```
|
|
|
|
Query parameters:
|
|
|
|
- `sort`: `popular`, `prompts`, `new`, `rating`
|
|
- `limit`: number of creators
|
|
- `search`: optional search term
|
|
|
|
Response: list of creator cards including follow state and avatar URL.
|
|
|
|
### Public Profile
|
|
|
|
```http
|
|
GET /api/v1/profiles/{creatorId}
|
|
```
|
|
|
|
Used by public creator profiles. The response contains display name, slug, bio, avatar URL, average rating and subscriber count.
|
|
|
|
### Update Profile
|
|
|
|
```http
|
|
PUT /api/v1/profiles
|
|
Content-Type: application/json
|
|
```
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"displayName": "Belle",
|
|
"userName": "lady_belle",
|
|
"slug": "lady_belle",
|
|
"bio": "Prompt creator",
|
|
"avatarUrl": "data:image/png;base64,...",
|
|
"specialities": null,
|
|
"isPublic": true
|
|
}
|
|
```
|
|
|
|
Updates profile data used on My Profile, Community and the topbar.
|
|
|
|
## Prompts
|
|
|
|
### List Prompts
|
|
|
|
```http
|
|
GET /api/v1/prompts?sortBy=date&ascending=false&limit=50&search=cat
|
|
```
|
|
|
|
Used by Marketplace. Supports sorting, search and category filtering. The marketplace excludes prompts created by the logged-in user.
|
|
|
|
Response items include prompt title, description, creator id, creator name, creator avatar, example image, tier data, like/save counts, average rating, review count and access state.
|
|
|
|
### Feed
|
|
|
|
```http
|
|
GET /api/v1/feed?sortBy=date&ascending=false&limit=20
|
|
```
|
|
|
|
Used by Dashboard. Returns prompt cards from followed creators, excluding the logged-in user's own prompts.
|
|
|
|
### Create Prompt
|
|
|
|
```http
|
|
POST /api/v1/prompts
|
|
Content-Type: application/json
|
|
```
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"title": "Luxury Cat Portrait",
|
|
"description": "Create a premium cat portrait prompt.",
|
|
"content": "Write the full prompt instructions here.",
|
|
"category": "art",
|
|
"subscriptionTier": null,
|
|
"slug": null,
|
|
"exampleOutput": "Example output text",
|
|
"exampleImageUrl": "data:image/png;base64,...",
|
|
"price": null
|
|
}
|
|
```
|
|
|
|
Response: created prompt. The frontend redirects to `/post-detail?id={id}`.
|
|
|
|
`subscriptionTier` is the creator's tier level. `null` means the prompt is public/free. `price` is kept as `null` because prompt access is handled through monthly creator tiers.
|
|
|
|
### Own Prompts
|
|
|
|
```http
|
|
GET /api/v1/prompts/mine
|
|
```
|
|
|
|
Used by My Profile to show prompts created by the logged-in user.
|
|
|
|
### Update Prompt
|
|
|
|
```http
|
|
PUT /api/v1/prompts/{id}
|
|
Content-Type: application/json
|
|
```
|
|
|
|
Request body uses the same editable fields as prompt creation, including `subscriptionTier`. Used by the edit prompt flow.
|
|
|
|
### Prompt Detail
|
|
|
|
```http
|
|
GET /api/v1/prompts/{id}
|
|
```
|
|
|
|
Response includes:
|
|
|
|
- title and description
|
|
- prompt content if accessible
|
|
- category
|
|
- creator information
|
|
- tier or free state
|
|
- example output
|
|
- example image
|
|
- average rating and review count
|
|
- like/save state and counts
|
|
|
|
Tier prompts return no detail content for users without a matching creator subscription.
|
|
|
|
### Likes and Saves
|
|
|
|
```http
|
|
PUT /api/v1/prompts/{id}/likes
|
|
DELETE /api/v1/prompts/{id}/likes
|
|
PUT /api/v1/prompts/{id}/saves
|
|
DELETE /api/v1/prompts/{id}/saves
|
|
```
|
|
|
|
Used by Dashboard, prompt detail and profile tabs to store user interactions.
|
|
|
|
### Reviews
|
|
|
|
```http
|
|
GET /api/v1/prompts/{id}/reviews
|
|
PUT /api/v1/prompts/{id}/reviews
|
|
```
|
|
|
|
`PUT` request:
|
|
|
|
```json
|
|
{
|
|
"comment": "Helpful prompt",
|
|
"rating": 5
|
|
}
|
|
```
|
|
|
|
Used on the prompt detail page. Users can review prompts created by other users. Each user can have one review per prompt; submitting again updates the existing review. Reviews are displayed with username, star rating and comment.
|
|
|
|
## Categories
|
|
|
|
### Minimal Categories
|
|
|
|
```http
|
|
GET /api/v1/categories/minimal
|
|
```
|
|
|
|
Used by Create New and Marketplace filters.
|
|
|
|
Response:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"name": "Art",
|
|
"slug": "art"
|
|
}
|
|
]
|
|
```
|
|
|
|
Default categories are created automatically when the backend starts.
|
|
|
|
## Subscriptions
|
|
|
|
### Follow or Subscribe to Creator
|
|
|
|
```http
|
|
GET /api/v1/subscriptions/{creatorId}
|
|
PUT /api/v1/subscriptions/{creatorId}
|
|
PUT /api/v1/subscriptions/{creatorId}/{level}
|
|
DELETE /api/v1/subscriptions/{creatorId}
|
|
```
|
|
|
|
Used by Community, public profiles and locked prompt details to read follow state, follow creators, subscribe to a monthly tier or unfollow creators.
|
|
|
|
- `PUT /api/v1/subscriptions/{creatorId}` follows a creator without a paid tier.
|
|
- `PUT /api/v1/subscriptions/{creatorId}/{level}` subscribes to one of the creator's tiers. A higher tier gives access to prompts from the same level and lower levels.
|
|
|
|
### Subscription Tiers
|
|
|
|
```http
|
|
GET /api/v1/subscriptions/tiers
|
|
GET /api/v1/subscriptions/tiers/{creatorId}
|
|
POST /api/v1/subscriptions/tiers
|
|
PUT /api/v1/subscriptions/tiers/{tierId}
|
|
DELETE /api/v1/subscriptions/tiers/{tierId}
|
|
```
|
|
|
|
Used by the Subscription Tiers page, Create Prompt and public creator profiles.
|
|
|
|
Create request:
|
|
|
|
```json
|
|
{
|
|
"name": "Supporter",
|
|
"monthlyPrice": 4.99,
|
|
"level": 1,
|
|
"description": "Access to basic premium prompts."
|
|
}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"id": "uuid",
|
|
"name": "Supporter",
|
|
"level": 1,
|
|
"monthlyPrice": 4.99,
|
|
"description": "Access to basic premium prompts."
|
|
}
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
Common response codes used by the frontend:
|
|
|
|
- `200 OK`: request succeeded
|
|
- `400 Bad Request`: validation error or invalid request data
|
|
- `401 Unauthorized`: user is not logged in and should be redirected to login
|
|
- `404 Not Found`: requested prompt, profile or subscription was not found
|
|
|
|
The frontend handles failed requests with visible error states or redirects to login for unauthorized users.
|