> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fucksornot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the FoN API

## Overview

The FoN API is a RESTful API that allows you to interact with the FoN platform programmatically. All requests should be made to the base URL:

```
https://fucksornot.com
```

## Authentication

Most endpoints require authentication, using one of three mechanisms depending on the endpoint:

<CardGroup cols={2}>
  <Card title="Session Cookie" icon="cookie">
    `Cookie: auth-token=<jwt>` — used by almost all endpoints (voting, tags, profile, uploads, MFA, password management, etc.)
  </Card>

  <Card title="JWT Bearer Token" icon="key">
    `Authorization: Bearer <jwt>` — used only by the `/api/auth/tokens` token-management endpoints
  </Card>

  <Card title="API Token" icon="terminal">
    `Authorization: Bearer <api_token>` — used only by `/api/v1/upload`
  </Card>
</CardGroup>

```bash theme={null}
# Using the session cookie (most endpoints)
curl https://fucksornot.com/api/profile \
  -H "Cookie: auth-token=YOUR_JWT_TOKEN"
```

See the [Authentication guide](/authentication) for full details, and each endpoint's reference page for which mechanism it expects.

## Request Format

### JSON Requests

For endpoints that accept JSON, set the `Content-Type` header:

```bash theme={null}
curl -X POST https://fucksornot.com/api/auth \
  -H "Content-Type: application/json" \
  -d '{"action": "login", "email": "...", "password": "..."}'
```

### Form Data

For file uploads, use `multipart/form-data`:

```bash theme={null}
curl -X POST https://fucksornot.com/api/upload \
  -H "Cookie: auth-token=YOUR_JWT_TOKEN" \
  -F "upload_type=image" \
  -F "description=My upload" \
  -F "file=@image.jpg"
```

## Response Format

All responses are returned as JSON. There is no wrapper envelope — successful responses return the resource or domain object directly. For example, `GET /api/uploads` returns:

```json theme={null}
{
  "uploads": [...],
  "page": 1,
  "limit": 10
}
```

### Error Responses

Errors follow the standard Nitro/H3 error shape, with a `statusCode`, `statusMessage`, and a descriptive `message`:

```json theme={null}
{
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or expired token"
}
```

## HTTP Status Codes

| Code  | Description                            |
| ----- | -------------------------------------- |
| `200` | Success                                |
| `304` | Not Modified (cached)                  |
| `400` | Bad Request - Invalid input            |
| `401` | Unauthorized - Authentication required |
| `403` | Forbidden - Insufficient permissions   |
| `404` | Not Found - Resource doesn't exist     |
| `429` | Too Many Requests - Rate limited       |
| `500` | Internal Server Error                  |

## Rate Limits

The API enforces rate limits to ensure fair usage:

| Endpoint Category | Limit        | Window     |
| ----------------- | ------------ | ---------- |
| Authentication    | 10 requests  | 15 minutes |
| Uploads           | 20 requests  | 1 hour     |
| Voting            | 30 requests  | 1 minute   |
| Anonymous voting  | 10 requests  | 1 minute   |
| General           | 100 requests | 1 minute   |

When rate limited, you'll receive a `429` response with a `Retry-After` header.

## Pagination

List endpoints support pagination via query parameters:

| Parameter | Type    | Default | Description              |
| --------- | ------- | ------- | ------------------------ |
| `page`    | integer | 1       | Page number (1-indexed)  |
| `limit`   | integer | 10      | Items per page (max 100) |

```bash theme={null}
curl "https://fucksornot.com/api/uploads?page=2&limit=20"
```

Response includes pagination info:

```json theme={null}
{
  "uploads": [...],
  "page": 2,
  "limit": 20
}
```

## Caching

The API uses caching to improve performance:

| Endpoint            | Cache Duration  |
| ------------------- | --------------- |
| `/api/uploads`      | 2 minutes       |
| `/api/items-recent` | 5 minutes       |
| `/api/profile`      | 30 seconds      |
| `/api/image/{id}`   | 1 year (public) |

Use the `ETag` header for conditional requests.

## OpenAPI Specification

The complete API is documented using OpenAPI 3.1. You can:

<Card title="View OpenAPI Spec" icon="file-code" href="/api-reference/openapi.json">
  Download the full OpenAPI specification
</Card>

## Endpoints

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/api-reference/auth/register-login">
    User registration, login, and session management
  </Card>

  <Card title="Uploads" icon="upload" href="/api-reference/uploads/create">
    Create, manage, and browse uploads
  </Card>

  <Card title="Voting" icon="thumbs-up" href="/api-reference/voting/submit-vote">
    Vote on content
  </Card>

  <Card title="Tags" icon="tag" href="/api-reference/tags/list">
    Tag management and discovery
  </Card>

  <Card title="Media" icon="image" href="/api-reference/media/images">
    Image and thumbnail retrieval
  </Card>
</CardGroup>