API Documentation

Programmatic access to f0ck.org. All endpoints return JSON. Rate limits apply per IP or API key.

Getting Started

The f0ck.org API is a RESTful interface for interacting with the platform. Include Accept: application/json in requests. Use an API key via the X-API-Key header for higher rate limits and programmatic access.

Base URL

https://f0ck.org

Format

JSON (application/json)

Authentication

Session or X-API-Key

API Key Authentication

API keys provide programmatic access with higher rate limits. Create keys at Settings → API Keys. Include the key in the X-API-Key header.

Tier	Rate Limit	Max Keys	Price
Free	30 req/hour	0 (session only)	Free
Basic	200 req/hour	1	$3/mo
Pro	1,000 req/hour	3	$7/mo
Enterprise	5,000 req/hour	5	$15/mo

None

Rate: 50 req/min per IP

Query Parameters

Name	Type	Default	Description
offset	number	0	Pagination offset
limit	number	28	Results per page (max 100)
search	string	—	Text search in title and tags
uploader	string	—	Filter by uploader username
tag	string	—	Filter by tag (can be repeated)
sortBy	string	newest	Sort order
contentRating	string	—	Filter by rating: safe, sketchy, unsafe
minLikes	number	—	Minimum likes threshold
dateFrom	string	—	ISO date start range
dateTo	string	—	ISO date end range

Response

{
  "posts": [
    {
      "id": "64f1a2b3c4d5e6f7a8b9c0d1",
      "title": "My Post",
      "thumbnail": "/uploads/thumb.jpg",
      "imageUrl": "/uploads/full.jpg",
      "likes": 42,
      "comments": 7,
      "contentRating": "safe",
      "author": { "username": "user123" },
      "tags": ["funny", "cat"]
    }
  ],
  "totalPosts": 150,
  "currentPage": 1,
  "totalPages": 6
}

cURL Example

terminal

curl "https://f0ck.org/api/posts?limit=10&sortBy=most_liked&tag=cat"

None

Rate: 50 req/min per IP

Response

{
  "id": "64f1a2b3c4d5e6f7a8b9c0d1",
  "title": "My Post",
  "content": "Post description text",
  "imageUrl": "/uploads/full.jpg",
  "mediaType": "image",
  "stats": { "likes": 42, "comments": 7, "favorites": 3 },
  "contentRating": "safe",
  "author": {
    "id": "64f1a2b3c4d5e6f7a8b9c0d2",
    "username": "user123",
    "avatar": "/avatars/user123.jpg"
  },
  "tags": ["funny", "cat"],
  "createdAt": "2024-01-15T10:30:00.000Z"
}

cURL Example

terminal

curl "https://f0ck.org/api/posts/64f1a2b3c4d5e6f7a8b9c0d1"

None

Rate: 50 req/min per IP

Query Parameters

Name	Type	Default	Description
search	string	—	Search tag names
page	number	1	Page number
limit	number	20	Results per page
sortBy	string	most_used	Sort: most_used, newest, alphabetical, trending
author	string	—	Filter by author's posts
timeRange	string	all	Time filter: day, week, month, year, all

Response

{
  "tags": [
    {
      "_id": "64f1a2b3c4d5e6f7a8b9c0d3",
      "name": "cat",
      "postsCount": 1523,
      "newPostsToday": 12,
      "newPostsThisWeek": 67
    }
  ],
  "pagination": {
    "total": 340,
    "page": 1,
    "perPage": 20,
    "totalPages": 17
  }
}

cURL Example

terminal

curl "https://f0ck.org/api/tags?search=cat&sortBy=most_used"

None

Rate: 50 req/min per IP

Response

{
  "pools": [
    {
      "_id": "64f1a2b3c4d5e6f7a8b9c0d4",
      "name": "Best Cats 2024",
      "description": "Curated collection of cat posts",
      "postCount": 45,
      "isPublic": true,
      "creator": { "username": "user123" }
    }
  ],
  "totalPools": 28,
  "page": 1,
  "totalPages": 3
}

cURL Example

terminal

curl "https://f0ck.org/api/pools?page=1&limit=20"

None

Rate: 30 req/min per IP

Response

{
  "activeUsers24h": 142,
  "newPosts24h": 89,
  "newComments24h": 234,
  "totalPosts": 15230,
  "totalComments": 89210,
  "totalUsers": 5678,
  "totalTags": 340,
  "serverStatus": "healthy",
  "version": "5.5.0"
}

cURL Example

terminal

curl "https://f0ck.org/api/public/status"

None

Rate: 50 req/min per IP

Response

{
  "username": "user123",
  "bio": "I love cats",
  "avatar": "/avatars/user123.jpg",
  "createdAt": "2023-06-15T08:00:00.000Z",
  "stats": {
    "uploads": 156,
    "comments": 89,
    "favorites": 42,
    "likes": 234
  }
}

cURL Example

terminal

curl "https://f0ck.org/api/users/user123"

User session required

Rate: 10 req/min per user

Request Body

{
  "file": <binary>,
  "title": "My upload",
  "tags": "funny,cat",
  "contentRating": "safe",
  "isNSFW": false
}

Response

{
  "message": "Upload successful",
  "post": {
    "id": "64f1a2b3c4d5e6f7a8b9c0d5",
    "title": "My upload",
    "imageUrl": "/uploads/full.jpg",
    "thumbnailUrl": "/uploads/thumb.jpg",
    "mediaType": "image"
  }
}

cURL Example

terminal

curl -X POST "https://f0ck.org/api/upload" \
  -H "Cookie: next-auth.session-token=<token>" \
  -F "[email protected]" \
  -F "title=My upload" \
  -F "tags=funny,cat" \
  -F "contentRating=safe"

User session required

Rate: 10 req/min per user

Request Body

{
  "postId": "64f1a2b3c4d5e6f7a8b9c0d1",
  "content": "Great post!",
  "parentId": null
}

Response

{
  "message": "Comment posted",
  "comment": {
    "id": "64f1a2b3c4d5e6f7a8b9c0d6",
    "content": "Great post!",
    "author": {
      "username": "user123",
      "avatar": "/avatars/user123.jpg"
    },
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

cURL Example

terminal

curl -X POST "https://f0ck.org/api/comments" \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=<token>" \
  -d '{
    "postId": "64f1a2b3c4d5e6f7a8b9c0d1",
    "content": "Great post!"
  }'

X-API-Key header required

Rate: 5 req/min per user

Request Body

{
  "name": "My integration"
}

Response

{
  "id": "64f1a2b3c4d5e6f7a8b9c0d7",
  "key": "f0ck_live_abc123...",
  "name": "My integration",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

cURL Example

terminal

curl -X POST "https://f0ck.org/api/user/api-keys" \
  -H "X-API-Key: f0ck_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My integration"}'

X-API-Key header required

Rate: 5 req/min per user

Response

{
  "keys": [
    {
      "id": "64f1a2b3c4d5e6f7a8b9c0d7",
      "name": "My integration",
      "lastUsed": "2024-01-15T10:00:00.000Z",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "isActive": true
    }
  ]
}

cURL Example

terminal

curl "https://f0ck.org/api/user/api-keys" \
  -H "X-API-Key: f0ck_live_abc123..."

X-API-Key header required

Rate: 5 req/min per user

Request Body

{
  "keyId": "64f1a2b3c4d5e6f7a8b9c0d7"
}

Response

{
  "message": "API key revoked successfully"
}

cURL Example

terminal

curl -X DELETE "https://f0ck.org/api/user/api-keys" \
  -H "X-API-Key: f0ck_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"keyId": "64f1a2b3c4d5e6f7a8b9c0d7"}'

Error Handling

Errors return HTTP status codes with a JSON body. Rate-limited requests include a Retry-After header.

404 — Not Found

{
  "error": "Post not found",
  "status": 404
}

429 — Rate Limited

{
  "error": "Rate limit exceeded. Try again in 32 seconds.",
  "retryAfter": 32
}

401 — Unauthorized

{
  "error": "Invalid API key"
}

Rate Limits

IP-based limits apply when no API key is provided
API key limits are per-user and based on your premium tier
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
429 responses include Retry-After header
Read endpoints have higher limits than write endpoints

Showing 11 of 11 endpoints