API Reference

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:

Session Cookie

Cookie: auth-token=<jwt> — used by almost all endpoints (voting, tags, profile, uploads, MFA, password management, etc.)

JWT Bearer Token

Authorization: Bearer <jwt> — used only by the /api/auth/tokens token-management endpoints

API Token

Authorization: Bearer <api_token> — used only by /api/v1/upload

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

See the Authentication guide 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:

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:

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:

{
  "uploads": [...],
  "page": 1,
  "limit": 10
}

Error Responses

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

{
  "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)

curl "https://fucksornot.com/api/uploads?page=2&limit=20"

Response includes pagination info:

{
  "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:

View OpenAPI Spec

Download the full OpenAPI specification

Endpoints

Authentication

User registration, login, and session management

Uploads

Create, manage, and browse uploads

Voting

Vote on content

Media

Image and thumbnail retrieval

Overview

Authentication

Uploads

Voting

Tags

Media

User

Overview

Authentication

Session Cookie

JWT Bearer Token

API Token

Request Format

JSON Requests

Form Data

Response Format

Error Responses

HTTP Status Codes

Rate Limits

Caching

OpenAPI Specification

View OpenAPI Spec

Endpoints

Authentication

Uploads

Voting

Tags

Media

​Overview

​Authentication

Session Cookie

JWT Bearer Token

API Token

​Request Format

​JSON Requests

​Form Data

​Response Format

​Error Responses

​HTTP Status Codes

​Rate Limits

​Pagination

​Caching

​OpenAPI Specification

View OpenAPI Spec

​Endpoints

Authentication

Uploads

Voting

Tags

Media

Overview

Authentication

Request Format

JSON Requests

Form Data

Response Format

Error Responses

HTTP Status Codes

Rate Limits

Pagination

Caching

OpenAPI Specification

Endpoints