# 4chan API: a read-only JSON contract you implement yourself

> The 4chan/4chan-API repository is the written specification for 4chan's read-only JSON API, not a library you can install. It tells you which host serves the data, which verbs work, how often you may call it, and what the terms let you build.

**4chan/4chan-API** — Documentation for 4chan's read-only JSON API.

- Repository: https://github.com/4chan/4chan-API
- Website: http://www.4chan.org/
- Stars: 1,113 · Forks: 75
- Language: Unknown
- License: not declared
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/4chan-4chan-api

## A documentation repository, not a client library

The repository 4chan/4chan-API is not a client library and not a service you install. Its top level holds README.md and a pages/ directory, and the project describes itself as documentation for 4chan's read-only JSON API, a service the getting started section says was originally launched in September of 2012. There is no source tree to compile, no package manifest, no license file among the top level entries, and the project has no GitHub releases at all. That shape matters for adoption, because nothing here runs on a server for you and nothing here needs to be deployed. What you consume is the written contract, then you write a small HTTP client of your own and point it at the content host.

The audience is narrow but clear. Engineers building dashboards, archives, moderation tooling, or research scripts that need structured post data rather than scraped HTML need this, and so do people who have to answer what the rate limits and the terms are before shipping. Teams that expect an official SDK, a typed package, or a changelog will not find one here. The last push to the repository was on 2026-08-07, and with no tagged releases, the commit history and the documentation pages are the only record of how the API is expected to behave.

## Only a.4cdn.org will return API data

The getting started section draws a line that decides where your traffic goes. Data from the 4chan API is exclusively accessible from a.4cdn.org, over http:// or https://, and the documentation notes that all examples use https://. The human-facing boards live at 4chan.org and 4channel.org, and it is their JSON representations that the CDN host serves. If an integration plan still points at a board domain, it will not work. The data path and the browsing path are separate hosts, and the text says so without hedging.

The request surface is equally small. CORS is supported from the origins boards.4chan.org and boards.4channel.org, over either protocol, and only three HTTP methods are accepted:

```text
GET
OPTIONS
HEAD
```

There is no mention of POST, PUT, or any other write verb, which matches the read-only framing of the whole service. There is also no mention of an API key, a token, or any credential. A browser page served from a permitted origin can therefore read the same JSON that a server-side script would, as long as it stays on the listed origins and the listed host. A page on any other domain will be blocked by the same-origin policy rather than by a server-side check.

## Assembling your first request from the endpoint pages

The repository prints no copy and paste example request, so a first client is assembled from the values the documentation states outright. The host and the two allowed schemes come from the getting started section:

```text
a.4cdn.org
http://
https://
```

The methods and the conditional request header come from the accepted request types and the third API rule:

```text
GET
OPTIONS
HEAD
If-Modified-Since
```

Put together, that is one GET request to the a.4cdn.org host, over http:// or https:// depending on how your own app is served, with an If-Modified-Since header when you are polling. The resource path is the one thing the top level files do not spell out, and it is documented per resource in the pages directory, where the Boards.json page covers the 4chan board list and its attributes, and the Catalog, Index, Thread, Threadlist, and Archive pages each cover their own JSON representation. A first useful call is therefore the board list, because its page is the one that explains what the attributes mean before you move on to threads.

One convenience is documented for inspection rather than for code. The README points readers to JSONLint to view a pretty-printed version of the thread, index, and catalog JSON. If you are checking a payload by hand, that saves you from formatting it locally, and the same note applies the first time you read a catalog or index payload.

## The four API rules are a contract you enforce yourself

Four lines in the API Rules section carry the operational weight of the whole service, and none of them are backed by a documented quota, a limit header, or an error schema.

First, do not make more than one request per second. Second, thread updating should be set to a minimum of 10 seconds, preferably higher. Third, use If-Modified-Since when making your requests. Fourth, make API requests using the same protocol as the app, and only use SSL when a user is accessing your app over HTTPS. That last rule has a concrete effect on browser clients: a page served over plain http should call the http endpoint, and a page served over https should call the https one.

The interesting part is who polices this. The documentation states obligations, not mechanisms, so a compliant client is one you write with a request scheduler and a conditional request cache. Nothing in the repository describes what happens when the limits are exceeded, whether the host answers with 429, whether there are Retry-After semantics, or whether access is rate limited by address. If your application depends on predictable throttling behaviour, that behaviour is the part you have to verify yourself before you depend on it.

## Eight documentation pages, one topic each

The table of contents is a good map of what the API actually exposes, and it is worth reading as a list of resources rather than as a reading plan. The first page covers endpoints and site domains, a quick rundown of all API endpoints and the site domains behind them. The second covers media and static content, including paths for spoiler images, country flags, capcodes, and user submitted media. The remaining pages are each a single resource: Archive.json for the native archive and its JSON, Boards.json for the board list and its attributes, Catalog.json for the board catalog, an index endpoint for the board index pages, a thread endpoint for specific threads, and a thread list for the board threadlist with its brief stats.

Read as a set, that is a complete read-only surface: the board catalogue, the list of boards, per board listings, per thread contents, a persistent archive, and the static media paths. There is no endpoint for writing, no endpoint for user accounts, and no endpoint for search. Notably, the same data appears in more than one shape, since a thread can be reached through the thread endpoint, the thread list, the catalog, and the archive. The documentation does not explain whether those views are byte-identical, so a client that mixes them should not assume they are.

Support for the project itself runs through an issue tracker and an address, api@4chan.org. The same footer suggests the obvious etiquette for anyone unsure about a field: ask before shipping code that depends on it.

## The terms of service rule out the obvious mirror

Six clauses in the API Terms of Service matter more to a real project than most of the endpoint details, because they decide what you may ship. You may not use the word 4chan in the title of your application, product, or service. You may not use the 4chan name, logo, or brand to promote it. You must disclose the source of the information your application shows as 4chan, and provide a link. You may not market the product or service as official in any way. You may not clone 4chan or its existing features, and the documentation gives the concrete example: do not pull the JSON down, host it elsewhere, and put ads around it.

That fifth clause is the one that changes architecture. The tempting design for a fast reader is a small server that pulls from the API, caches aggressively, and serves the result to many clients, but that is precisely the mirror the text warns about, and the aggressive caching also runs into the one request per second rule. A personal dashboard that fetches on demand is a different shape from a public mirror, and the documentation does not draw that line for you. The last clause adds that the terms are subject to change without notice, so they are a moving target rather than a fixed contract, and the last push on 2026-08-07 does not tell you when they last changed.

Attribution is the part that is easy to get wrong, since it is a hard obligation rather than a courtesy. Source disclosure with a link, no official-sounding branding, and no 4chan in the product title.

## Direct calls versus hosting your own copy

Two alternative approaches come up in practice, and the documentation speaks to both, if only indirectly. The first is to scrape the board pages at 4chan.org and 4channel.org with an HTML parser. The difference in approach is real: you would parse markup instead of reading a JSON document, you would hit the browsing hosts rather than a.4cdn.org, and you would lose the structured, per resource representation that the API pages describe. Nothing in the repository discusses scraping, so the rules on request rate and the CORS origins simply do not apply to that path, and you would be relying on markup that is not versioned or documented. It also puts you further from the terms, which speak about information shown by your application and its disclosure of 4chan as the source.

The second alternative is to run your own copy of the JSON, serving it to your own clients. This is the approach the terms explicitly reject, using the mirror and advertising example. The stated difference in approach is therefore not technical but contractual: a direct client obeys a request budget and attributes its source, while a hosted copy removes the request budget and removes the source from the picture, which is the part the terms prohibit.

The practical middle ground the documentation implies is a thin direct client with caching on the client side, using If-Modified-Since to keep request counts down, and running inside one of the two permitted CORS origins if the output is shown in a browser.

## Where the documentation stops, and what to check first

Several things an engineer would look for are simply not in the repository, and the honest answer is to name the gap rather than infer a behaviour. There is no API version number, no changelog, and no release history, so a client cannot detect a breaking change the way it might with a versioned HTTP API. There is no documented error format, no list of status codes, and no description of the response headers beyond the ones the rules mention. Field level behaviour is described across the resource pages, and the top level listing of README.md and pages/ tells you the repository holds nothing else. No client library in any language is offered, so every consumer maintains its own HTTP code.

Maintenance is modest rather than dormant. The last push was on 2026-08-07, the project is not archived, and there are no GitHub releases to track. For a service whose contract is a set of markdown pages, that means the cost of keeping up is reading the changed pages rather than reading release notes, which is a different kind of upgrade habit.

So the first thing to check is the endpoint page for the exact resource you need, then confirm which host and protocol your client will use, then read the terms again since they change without notice. If a stable, versioned, licensed contract matters more to you than the speed of reading the JSON, the documentation will not give you that.

## Conclusion

Adopt the documented endpoints if you need structured post data and can live with a one request per second limit you enforce yourself. Skip it if you need a versioned contract, a license, or a stability guarantee. Before writing code, read the endpoint page for your resource and reread the current terms, since the rules can change without notice.

## FAQ

### Does the 4chan API need an API key or any authentication?

The documentation describes a read-only service with no credential step. The getting started section lists only GET, OPTIONS, and HEAD as accepted request types, and the API Rules mention only request rate, the If-Modified-Since header, and protocol choice, with no key, token, or login anywhere.

### How many requests per second can I send to the 4chan API?

The API Rules state that you should not make more than one request per second, and that thread updating should be set to a minimum of 10 seconds, preferably higher. These are stated as rules for clients, and the documentation does not describe any limit headers or throttling mechanism.

### Can I host my own mirror of the 4chan API JSON?

The terms of service state that you may not clone 4chan or its existing features, and they give the example of pulling the JSON down, hosting it elsewhere, and putting ads around it. You must also disclose 4chan as the source of the information you show, with a link.

### Which host serves the 4chan API and which HTTP methods are accepted?

Data is exclusively accessible from a.4cdn.org over http:// or https://, with all documentation examples using https://. CORS is supported from the origins boards.4chan.org and boards.4channel.org, and the accepted request types are GET, OPTIONS, and HEAD.

### Does the 4chan API have versioned endpoints or a changelog?

The repository has no GitHub releases, and the top level entries are README.md and a pages/ directory. The documentation does not expose an API version number or a changelog, so the per resource pages under pages/ are where behaviour is described.

## Sources

- [4chan/4chan-API on GitHub](https://github.com/4chan/4chan-API)
- [Issues](https://github.com/4chan/4chan-API/issues)
- [Project website](http://www.4chan.org/)
- [README](https://github.com/4chan/4chan-API/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/4chan-4chan-api