booru-api/DOCS.md

Booru API Documentation

A unified API for accessing multiple booru image boards.

Base URL

http://localhost:6600

Supported Boorus

Booru	Aliases	Status
rule34.xxx	rule34, r34, rule34xxx	✅ Enabled
safebooru.org	safebooru, sb, s34	✅ Enabled
tbib.org	tbib, tb, tbiborg	✅ Enabled
hypnohub.net	hypnohub, hh, hypnohubnet	✅ Enabled
xbooru.com	xbooru, xb, xboorucom	✅ Enabled
e621.net	e621, e6, e621net	✅ Enabled
gelbooru.com	gelbooru, gb, gelboorucom	✅ Enabled
realbooru.com	realbooru, rb, real34, realb	❌ Disabled

Authentication

E621

Required headers for e621 requests:

e621UserAgent: YourApplication/1.0 (by username on e621)
e621Username: your-username
e621ApiKey: your-apikey

Gelbooru

Required headers for Gelbooru requests:

gelbooruApiKey: your-apikey
gelbooruUserId: your-user-id

Endpoints

1. Search Posts

Search for posts with specific tags.

POST /{booru}/search
Content-Type: application/json

Request Body:

{
  "tags": ["tag1", "tag2"],
  "excludeTags": ["unwanted_tag"],
  "page": 0,
  "results": 10,
  "tag_format": "formatted"
}

Parameters:

• tags (string|array): Tags to search for
• excludeTags (string|array): Tags to exclude
• page (number): Page number (default: 0)
• results (number): Number of results (default: 5)
• tag_format (string): Format of tags in response ("formatted" or "unformatted")

Example:

curl -X POST "http://localhost:6600/rule34/search" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["cat", "cute"],
    "results": 5
  }'

2. Random Posts

Get random posts with optional tag filtering.

POST /{booru}/random
Content-Type: application/json

Request Body:

{
  "tags": ["tag1", "tag2"],
  "excludeTags": ["unwanted_tag"],
  "results": 5,
  "tag_format": "formatted"
}

Example:

curl -X POST "http://localhost:6600/safebooru/random" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["anime"],
    "results": 3
  }'

3. Get Post by ID

Retrieve a specific post by its ID.

GET /{booru}/id/{id}?tag_format=formatted

Parameters:

• id (string): Post ID
• tag_format (query): Format of tags in response

Example:

curl "http://localhost:6600/rule34/id/123456?tag_format=formatted"

4. Tag Autocomplete

Get tag suggestions for autocomplete.

GET /{booru}/autocomplete/{tag}

Parameters:

• tag (string): Partial tag name (minimum 3 characters for e621)

Example:

curl "http://localhost:6600/safebooru/autocomplete/anim"

5. API Info

Get basic API information.

GET /

Example:

curl "http://localhost:6600/"

Response Format

Success Response

{
  "success": true,
  "code": 200,
  "posts": [
    {
      "id": 123456,
      "file_url": "https://example.com/image.jpg",
      "post_url": "https://example.com/post/123456",
      "tags": "tag1 tag2 tag3",
      "directory": 1234,
      "hash": "abcdef123456"
    }
  ]
}

Error Response

{
  "success": false,
  "code": 400,
  "error": "Missing booru parameter"
}

Error Codes

Code	Description
400	Bad Request - Missing or invalid parameters
401	Unauthorized - Missing authentication headers
403	Forbidden - Booru is disabled
404	Not Found - No results found or booru not found
405	Method Not Allowed - Wrong HTTP method
406	Not Acceptable - Wrong content type
500	Internal Server Error
501	Not Implemented - Feature not supported

Usage Examples

Search for anime posts on Safebooru

curl -X POST "http://localhost:6600/safebooru/search" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["anime", "girl"],
    "results": 10,
    "page": 0
  }'

Get random posts from Rule34

curl -X POST "http://localhost:6600/rule34/random" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["pokemon"],
    "excludeTags": ["gore"],
    "results": 5
  }'

Search E621 with authentication

curl -X POST "http://localhost:6600/e621/search" \
  -H "Content-Type: application/json" \
  -H "e621UserAgent: MyApp/1.0 (by myusername on e621)" \
  -H "e621Username: myusername" \
  -H "e621ApiKey: myapikey" \
  -d '{
    "tags": ["canine"],
    "results": 5
  }'

Get tag suggestions

curl "http://localhost:6600/gelbooru/autocomplete/anim" \
  -H "gelbooruApiKey: your-api-key" \
  -H "gelbooruUserId: your-user-id"

Rate Limiting

This API respects the rate limits of the underlying booru services. Please be mindful of your request frequency to avoid being blocked by the source APIs.

Notes

• All POST requests require Content-Type: application/json header
• Some boorus may have different response formats
• E621 requires authentication for all requests
• Gelbooru requires authentication for better rate limits
• Tag formats may vary between boorus
• The tag_format parameter allows you to choose between formatted strings or raw objects