Skip to content

API Reference Overview

FenLiu provides a comprehensive REST API for programmatic access to all features.

Base URL

http://localhost:8000/api/v1

For production, replace localhost:8000 with your FenLiu instance URL.

Authentication

All protected API endpoints require authentication via an API key. The API key is provided in the X-API-Key header.

API Key Authentication

Include your API key in the X-API-Key header:

curl -H "X-API-Key: your-api-key-here" \  # pragma: allowlist secret
  http://localhost:8000/api/v1/posts

For detailed authentication instructions, see the API Authentication Guide.

Generating an API Key

  1. Log in to FenLiu and navigate to Settings
  2. Scroll to API Key Management
  3. Click Generate New API Key
  4. Copy and save your key securely (it cannot be retrieved later)

Store your API key in an environment variable: 

export FENLIU_API_KEY="your-api-key-here"  # pragma: allowlist secret

Response Format

All API responses are JSON. Error responses include a detail field:

{
  "detail": "Descriptive error message"
}

Successful responses vary by endpoint (see specific documentation).

HTTP Status Codes

  • 200 OK - Request successful, response body included
  • 201 Created - Resource created, response body included
  • 204 No Content - Request successful, no response body
  • 400 Bad Request - Invalid input
  • 404 Not Found - Resource not found
  • 409 Conflict - Resource already exists or state conflict
  • 422 Unprocessable Entity - Validation error
  • 500 Internal Server Error - Server error

API Endpoints by Category

Hashtag Streams

Manage hashtag streams for monitoring.

  • GET /streams - List all streams
  • POST /streams - Create a new stream
  • GET /streams/{id} - Get stream details
  • PUT /streams/{id} - Update a stream
  • DELETE /streams/{id} - Delete a stream
  • POST /streams/{id}/fetch - Fetch posts for a stream
  • POST /streams/fetch-all - Fetch all active streams

Full Streams API documentation →

Posts

Retrieve and manage posts.

  • GET /posts - List posts with filtering
  • GET /posts/{id} - Get post details
  • PUT /posts/{id} - Update post
  • POST /posts/batch-score - Get batch scores
  • GET /posts?approved=true - Filter by status

Full Posts API documentation →

Review

Manage post reviews and feedback.

  • POST /posts/{id}/approve - Approve a post
  • POST /posts/{id}/reject - Reject a post
  • POST /posts/{id}/review - Submit full review
  • GET /posts?reviewed=true - List reviewed posts

Full Review API documentation →

Reblog Controls

Manage export filters and blocklists.

  • GET /reblog-controls/blocked-users - List blocked users
  • POST /reblog-controls/blocked-users - Add blocked user
  • DELETE /reblog-controls/blocked-users/{id} - Remove blocked user
  • GET /reblog-controls/blocked-hashtags - List blocked hashtags
  • POST /reblog-controls/blocked-hashtags - Add blocked hashtag
  • DELETE /reblog-controls/blocked-hashtags/{id} - Remove blocked hashtag
  • GET /reblog-controls/settings - Get export settings
  • PUT /reblog-controls/settings - Update export settings

Full Reblog Controls API documentation →

Curated Queue

Distribute approved posts to external consumers (e.g., Zhongli reblog bot).

  • GET /curated/next - Get next post for export (reserves it)
  • POST /curated/{id}/ack - Confirm successful export
  • POST /curated/{id}/nack - Return post to queue (transient error)
  • POST /curated/{id}/error - Mark as permanently failed
  • POST /curated/{id}/requeue - Requeue an errored post

Full Curated API documentation →

Statistics

Get system statistics and metrics.

  • GET /stats - Get overall statistics
  • GET /stats/posts - Get post statistics
  • GET /stats/streams - Get stream statistics

Full Statistics API documentation →

Common Patterns

Pagination

Endpoints that return lists support pagination:

GET /posts?skip=0&limit=50

Parameters: - skip - Number of items to skip (default: 0) - limit - Number of items to return (default: 100)

Filtering

Most list endpoints support filtering:

GET /posts?approved=true&spam_score_min=50&spam_score_max=100

Sorting

Endpoints return results sorted by creation date (newest first) by default.

Rate Limiting

Currently, FenLiu does not enforce rate limiting. Production deployments should add rate limiting via reverse proxy (nginx, Cloudflare, etc.).

Example Usage

Python

import requests

BASE_URL = "http://localhost:8000/api/v1"

# List streams
response = requests.get(f"{BASE_URL}/streams")
streams = response.json()

# Create a stream
response = requests.post(
    f"{BASE_URL}/streams",
    json={
        "hashtag": "python",
        "instance": "mastodon.social"
    }
)
stream = response.json()

JavaScript

const BASE_URL = "http://localhost:8000/api/v1";

// List streams
const streams = await fetch(`${BASE_URL}/streams`)
  .then(r => r.json());

// Create a stream
const stream = await fetch(`${BASE_URL}/streams`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    hashtag: "python",
    instance: "mastodon.social"
  })
}).then(r => r.json());

cURL

# List streams
curl http://localhost:8000/api/v1/streams

# Create a stream
curl -X POST http://localhost:8000/api/v1/streams \
  -H "Content-Type: application/json" \
  -d '{"hashtag":"python","instance":"mastodon.social"}'

Next Steps