API Docs

A pretty early, basically v0.1 version of the Gsbooru API is available for main post endpoint. Note: You must generate an API key to access any endpoint.

Authentication

To get an API key, navigate to your account settings page. The key will only be shown to you once upon generation. If you lose your key, you must regenerate a new one, which will immediately deactivate your previous key.

Requests must include the standard HTTP Authorization header using the Bearer token scheme:

Authorization: Bearer {api_key}

User-Agent

It is highly recommended that you provide a unique, descriptive User-Agent string in your request headers that identifies your script or application.

If you don't, then I don't know what script of yours is causing high load or errors, and I'll just have to reject your API key entirely.

Usage and Search Guidelines

API Endpoint currently available: /api/posts

The core API query structure aligns directly with the website's search engine. Review the Search Guide for syntax, tag combinations, and filtering rules.

The API endpoints accept the same search parameters, with the following additions:

limit: Integer. Specifies the number of posts to return per page. (Default: 20, Maximum: 100).
page: Integer. Specifies the page number of the results to retrieve.

Server Output

Things to note:

rating: Integer, not String. It follows the schema {0: "g", 1: "s", 2: "q", 3: "e"}
per_page: This is effectively the same thing as limit, it's at most how many posts were returned
total_pages: Specifies how many pages are available, given the supplied (or defaulted-to) limit

{
  "status": "ok",
  "posts": [
    {
      "id": 103660,
      "md5": "cd5540ab36c528d09da6baaa32547337",
      "has_preview": 1,
      "has_sample": 1,
      "file_ext": ".png",
      "tag_string": "1girl absurdres black_hair black_negligee ...",
      "rating": 1,
      "source": "https://www.pixiv.net/...",
      "score": 2,
      "is_soft_deleted": 0,
      "creator_id": 7,
      "created_at": "2026-04-15 04:18:15",
      "updated_at": "2026-04-15 04:18:15",
      "preview_url": "https://gsbooru.org/files/previews/...",
      "sample_url": "https://gsbooru.org/files/samples/...",
      "file_url": "https://gsbooru.org/files/images/..."
    }
  ],
  "current_page": 1,
  "total_pages": 192797,
  "per_page": 1,
  "total_posts": 192797
}

Troubleshooting

If you're only getting rating:general you might be querying the safe version of the site
If some posts or tags are not showing up, it's because it follows your blacklist, keep that in mind
If you have another issue, post it in the Api forum post

Rate Limits

The current rate limit is strictly 1 query per 5 seconds per API key.
I get that this is kind of low, but I want to monitor server load, it's subject to change.
I will come for you if you excessively hit the rate limit. Don't be that guy.