DOCSEARCHbyAlgolia
Submit Docs

4chan API Documentation

repository·master·Indexed 22 days ago

https://github.com/4chan/4chan-api

A read-only JSON API providing access to 4chan's board data, threads, and catalogs via the a.4cdn.org domain. Documentation covers available endpoints such as boards.json, catalog.json, and archive.json, as well as rate-limiting guidelines, CORS support, and terms of service for third-party application developers.

Tokens
10.7K
Snippets
21
Records
27
Agent score
78%

What's inside 4chan-api

  1. Understand the catalog.json data structure

    master

    The catalog.json file provides a paginated overview of threads on a specific board. The root of the JSON is an array of page objects. Each page object contains a page number and a threads array containing the thread data for that page.

    Structure Hierarchy:

    • Root (Array)
      • Page Object
        • page: Integer representing the page number.
        • threads: Array of thread objects.
          • Thread Object
            • Contains thread metadata (ID, subject, content, images).
            • last_replies: Array of recent reply objects.
            • last_modified: Timestamp of the last update.
    [
  {
    "page": 1,
    "threads": [
      {
        "no": 570368,
        "name": "Anonymous",
        "com": "Thread content...",
        "last_replies": [
          {
            "no": 570371,
            "name": "Anonymous",
            "com": "Reply content..."
          }
        ]
      }
    ]
  }
]

  2. Follow 4chan API usage rules

    master

    To ensure stability and compliance, follow these rate-limiting and request guidelines:

    1. Rate Limiting: Do not exceed one request per second.
    2. Thread Polling: When updating threads, set the interval to a minimum of 10 seconds (higher is preferred).
    3. Caching: Use the If-Modified-Since HTTP header in your requests to optimize bandwidth and respect server state.
    4. Protocol Consistency: Match the protocol of your application. Only use https:// if the end-user is accessing your application over HTTPS.

  3. Fetch a thread via the JSON API

    master

    To retrieve all posts within a specific thread, use the following URL pattern:

    /[board]/thread/[op ID].json

    Replace [board] with the target board name (e.g., po) and [op ID] with the original post ID of the thread.

    https://boards.4chan.org/board/thread/12345678.json

  4. Access static site content and flags

    master

    Static site images and assets are served via s.4cdn.org.

    Country Flags

    • Sprite sheet: https://s.4cdn.org/css/flags.css
    • Individual images: https://s.4cdn.org/image/country/[country code].gif

    Board Flags

    • Sprite sheet: https://s.4cdn.org/image/flags/[board]/flags.css
    • Individual images: https://s.4cdn.org/image/flags/[board]/[code].gif

    Spoiler Images

    • Standard spoiler: https://s.4cdn.org/image/spoiler.png
    • Custom spoilers: https://s.4cdn.org/image/spoiler-[board][1-5].png. Note that boards with custom spoilers enabled randomly assign one of these five images to spoilered content upon page refresh.
    https://s.4cdn.org/css/flags.css
https://s.4cdn.org/image/country/[country code].gif
https://s.4cdn.org/image/flags/[board]/flags.css
https://s.4cdn.org/image/flags/[board]/[code].gif
https://s.4cdn.org/image/spoiler.png
https://s.4cdn.org/image/spoiler-[board][1-5].png

  5. Access user images and thumbnails

    master

    User-submitted content and thumbnails are served via i.4cdn.org.

    • Original User Images: Use the pattern https://i.4cdn.org/[board]/[4chan image ID].[file extension].
    • Thumbnails: Use the pattern https://i.4cdn.org/[board]/[4chan image ID]s.jpg. Note the s suffix appended to the image ID and the .jpg extension.
    https://i.4cdn.org/[board]/[4chan image ID].[file extension]
https://i.4cdn.org/[board]/[4chan image ID]s.jpg

  6. 4chan API Terms of Service

    master

    When building applications using the 4chan API, you must adhere to the following legal requirements:

    • Naming: You may not use "4chan" in the title of your application, product, or service.
    • Branding: You may not use the 4chan name, logo, or brand to promote your application, product, or service.
    • Attribution: You must disclose that the source of the information is 4chan and provide a link to the source.
    • Official Status: You may not market your application or service as being "official" in any way.
    • Cloning Prohibited: You may not clone 4chan or its existing features/functionality. Specifically, do not scrape the JSON to host it elsewhere for the purpose of displaying advertisements.

    Note: These terms are subject to change without notice.

  7. Fetch a thread using /[board]/thread/[op ID].json

    master

    To retrieve a single thread containing the Original Post (OP) and all its replies, use the following URL pattern:

    https://a.4cdn.org/[board]/thread/[op ID].json

    Example URL: https://a.4cdn.org/po/thread/570368.json

    Response Details:

    • Status: 200
    • Content-Type: application/json
    https://a.4cdn.org/po/thread/570368.json

  8. Access the Archive JSON endpoint

    master

    To retrieve a list of archived thread IDs for a specific board, request the archive.json endpoint using the board's name. The endpoint follows the pattern https://a.4cdn.org/{board}/archive.json.

    Note that archived threads are read-only and closed to new replies/images. They are archived when pushed off the last page of a board. Not all boards have archives enabled.

    https://a.4cdn.org/po/archive.json

  9. Access the catalog.json API endpoint

    master

    The catalog.json endpoint provides a comprehensive JSON representation of a board's catalog page. It includes a list of all threads and their attributes, grouped by page. This is useful for retrieving a snapshot of all active threads on a specific board.

    Example URL Pattern: https://a.4cdn.org/[board]/catalog.json

    Example URL: https://a.4cdn.org/po/catalog.json

    Response Details:

    • Status: 200
    • Content-Type: application/json
    https://a.4cdn.org/po/catalog.json

  10. Access the 4chan API

    master

    The 4chan API is a read-only JSON API. All data must be accessed via the a.4cdn.org domain using either http:// or https:// protocols. The API serves JSON representations of posts from 4chan.org and 4channel.org boards.

    CORS Support: Cross-Origin Resource Sharing (CORS) is supported for requests originating from boards.4chan.org or boards.4channel.org.

    https://a.4cdn.org

  11. Example boards.json response structure

    master

    The following is a representative example of the JSON structure returned by boards.json, showing how different boards may have different sets of enabled attributes.

    {
	"boards": [{
		"board": "a",
		"title": "Anime \u0026 Manga",
		"ws_board": 1,
		"per_page": 15,
		"pages": 10,
		"max_filesize": 4194304,
		"max_webm_filesize": 3145728,
		"max_comment_chars": 2000,
		"max_webm_duration": 120,
		"bump_limit": 500,
		"image_limit": 300,
		"cooldowns": {
			"threads": 600,
			"replies": 60,
			"images": 60
		},
		"meta_description": "\u0026quot;\/a\/ - Anime \u0026amp; Manga\u0026quot; is 4chan's imageboard dedicated to the discussion of Japanese animation and manga.",
		"spoilers": 1,
		"custom_spoilers": 1,
		"is_archived": 1
	}, {
		"board": "b",
		"title": "Random",
		"ws_board": 0,
		"per_page": 15,
		"pages": 10,
		"max_filesize": 2097152,
		"max_webm_filesize": 2097152,
		"max_comment_chars": 2000,
		"max_webm_duration": 120,
		"bump_limit": 300,
		"image_limit": 150,
		"cooldowns": {
			"threads": 60,
			"replies": 15,
			"images": 15
		},
		"meta_description": "\u0026quot;\/b\/ - Random\u0026quot; is the birthplace of Anonymous, and where people go to discuss random topics and create memes on 4chan.",
		"forced_anon": 1,
		"board_flags": {
			"AB": "Flag Name AB",
			"XY": "Flag Name XY"
		}
	}],
}

  12. Fetch index page JSON via /[board]/[1-15].json

    master

    The /[board]/[1-15].json endpoint provides a representation of a single index page. Each JSON file returned includes every thread on that specific page along with its preview replies.

    Example URL: https://a.4cdn.org/po/2.json
    Response Status 200: Content-Type: application/json

    https://a.4cdn.org/po/2.json