# 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.