Build with The Chat Archive
Search public conversations, discover open datasets, and contribute from your own apps and scripts.
Base URL
https://thechatarchive.com/api/v1Quickstart
Call the official v1 endpoints from a server, notebook, command line, or browser. Public responses support cross-origin fetch requests.
cURL
curl 'https://thechatarchive.com/api/v1/catalog' curl 'https://thechatarchive.com/api/v1/conversations?q=python&limit=10' curl 'https://thechatarchive.com/api/v1/stats'
JavaScript
const response = await fetch('https://thechatarchive.com/api/v1/conversations?limit=10');
if (!response.ok) throw new Error(`API error: ${response.status}`);
const { items, next_cursor } = await response.json();
for (const item of items) {
console.log(item.publicId, item.title);
}Python (standard library)
import json
from urllib.request import urlopen
with urlopen('https://thechatarchive.com/api/v1/catalog') as response:
data = json.load(response)
for dataset in data['datasets']:
print(dataset['name'], dataset['license'])Try a public request
Live, read-only requests. No API key needed. An empty list means no matching records are published yet.
GET /api/v1/statsAuthentication & contributions
- Sign in with Google, GitHub, or email, then open Settings → API tokens.
- Create a labelled personal token. Copy it when shown; only its hash is stored.
- Keep the token in your server’s environment and send
Authorization: Bearer YOUR_TOKEN. Never embed a personal token in a public app. - Revoke tokens in Settings when an integration no longer needs access. Up to five active tokens are allowed.
Personal tokens have the submit scope. They can create private drafts and submit your reviewed conversations. Moderation, profile changes, token management, and removal of published records use the signed-in website. V1 writes require a bearer token, even if browser cookies are present.
Import a private draft
# Set CHAT_ARCHIVE_TOKEN in your environment first.
curl 'https://thechatarchive.com/api/v1/contributions/import' \
-H "Authorization: Bearer $CHAT_ARCHIVE_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"conversation":{"sourceFormat":"manual","title":"Understanding recursion","messages":[{"role":"user","content":"Explain recursion."},{"role":"assistant","content":"Recursion solves a problem by calling the same procedure on a smaller input, with a base case to stop."}]}}'The response contains draft conversation_id values. Review and redact each draft on the website, or call POST /drafts/{id} with its reviewed messages and all consent flags. Direct POST /conversations also requires consent and enters moderation.
{
"consent": {
"publish": true,
"redistribution": true,
"rights": true,
"third_parties": true,
"reviewed": true
}
}These flags attest to public publication and redistribution under CC BY 4.0, your right to share the content, protection of other people’s private information, and your review/redaction of the entire conversation. Set them only after completing that review. Privacy findings can return 422 and require correction or explicit acknowledgement.
Pagination, limits & errors
Conversation lists return items, next_cursor, and mode. For the next page, pass cursor=next_cursor with the same filters. Stop when the cursor is null. Page size is 1–50, default 20. For full-corpus access, use published release downloads; keyword search pagination is capped at 1,000 results.
- Public reads: 120 requests per minute per IP, shared across read endpoints.
- Writes: 20 requests per minute per account. Daily contribution caps are 10, 40, or 100 depending on trust level.
- Imports: up to 5 MiB and 200 conversations per file, subject to daily caps. Messages: up to 500 per conversation, 100,000 characters per message, and 400,000 total characters.
- On HTTP 429, wait for
Retry-Afterbefore retrying. Handle errors byerror.code; the message is for people. - Responses include
X-API-VersionandX-Request-ID. Share the request ID when reporting a failed call; never share your token. - V1 responses allow cross-origin requests without cookies. Only JSON request bodies are accepted for writes.
{
"error": {
"code": "not_found",
"message": "Not found"
}
}Empty collections return HTTP 200 with an empty array. Missing or unpublished conversations and releases return 404. Semantic search may be unavailable; in that case the response reports keyword mode and includes a notice. Existing unversioned site endpoints remain available, but new integrations should use v1.
Endpoint reference
get/api/v1
API version, capabilities, limits and resource links
get/api/v1/conversations
Search and browse approved public conversations
| Parameter | Location | Description |
|---|---|---|
| q | query | Keyword search in prompts and responses; max 200 characters. |
| mode | query | Semantic mode falls back to keyword search with a notice when unavailable. |
| provider | query | Provider slug. |
| model | query | Model slug. |
| tag | query | Topic slug. |
| language | query | Language code, for example en. |
| source | query | Source type. Fixtures appear only in development and remain labelled. |
| dataset | query | External source-catalog slug. |
| minTurns | query | Minimum user turns. |
| maxTurns | query | Maximum user turns. |
| minScore | query | Minimum community score. |
| from | query | Published on or after YYYY-MM-DD. |
| to | query | Published on or before YYYY-MM-DD. |
| corrections | query | Only conversations with a user correction. |
| evaluated | query | Only conversations with verified evaluation. |
| sort | query | Browse defaults to recent; keyword search defaults to relevance. |
| cursor | query | Opaque next_cursor from the previous response. Keep all other filters unchanged. |
| limit | query | Results per page. |
post/api/v1/conversations
Submit a consented conversation for moderationToken required
Requires a submit token and all five consent attestations. Never publishes immediately. Trust-level daily contribution caps also apply.
get/api/v1/search
Alias of GET /conversations, with the same filters and pagination
| Parameter | Location | Description |
|---|---|---|
| q | query | Keyword search in prompts and responses; max 200 characters. |
| mode | query | Semantic mode falls back to keyword search with a notice when unavailable. |
| provider | query | Provider slug. |
| model | query | Model slug. |
| tag | query | Topic slug. |
| language | query | Language code, for example en. |
| source | query | Source type. Fixtures appear only in development and remain labelled. |
| dataset | query | External source-catalog slug. |
| minTurns | query | Minimum user turns. |
| maxTurns | query | Maximum user turns. |
| minScore | query | Minimum community score. |
| from | query | Published on or after YYYY-MM-DD. |
| to | query | Published on or before YYYY-MM-DD. |
| corrections | query | Only conversations with a user correction. |
| evaluated | query | Only conversations with verified evaluation. |
| sort | query | Browse defaults to recent; keyword search defaults to relevance. |
| cursor | query | Opaque next_cursor from the previous response. Keep all other filters unchanged. |
| limit | query | Results per page. |
get/api/v1/conversations/{id}
Read an approved conversation, messages, attribution and license
| Parameter | Location | Description |
|---|---|---|
| id * | path | Lowercase public conversation ID returned as conversation_id or publicId. |
get/api/v1/conversations/{id}/download
Download one approved conversation as JSON
| Parameter | Location | Description |
|---|---|---|
| id * | path | Lowercase public conversation ID returned as conversation_id or publicId. |
get/api/v1/models
Models and providers with public conversation counts
get/api/v1/topics
Topics and their public conversation counts
get/api/v1/stats
Live archive counts
get/api/v1/leaderboard
Public contributor leaderboard, respecting anonymity and opt-outs
| Parameter | Location | Description |
|---|---|---|
| window | query | Leaderboard time window. |
| tag | query | Optional topic slug. |
| limit | query | Maximum entries. |
get/api/v1/catalog
External dataset metadata, licenses and hosted record counts
A catalog entry does not imply its records are hosted here. Check mirrored_records and redistribution.
get/api/v1/catalog/{slug}
Read one external dataset catalog entry
| Parameter | Location | Description |
|---|---|---|
| slug * | path | Source dataset slug, for example oasst2. |
get/api/v1/datasets
Published release summaries and external source-catalog summaries
get/api/v1/datasets/{version}
Published release manifest with partitions, files, licenses and checksums
| Parameter | Location | Description |
|---|---|---|
| version * | path | Published release version, for example v0.1. Never use a source-catalog slug here. |
get/api/v1/datasets/{version}/files/{path}
Stream a file listed in a published release manifest
The path may contain slashes. Only manifest-listed files, manifest.json and SHA256SUMS are allowed. Large datasets use these versioned JSONL.gz or Parquet downloads rather than the search API.
| Parameter | Location | Description |
|---|---|---|
| version * | path | Published release version, for example v0.1. Never use a source-catalog slug here. |
| path * | path | Relative manifest file path, such as community/community-00000.parquet. |
get/api/v1/users/{username}
Public profile without email, internal IDs or anonymous contribution links
| Parameter | Location | Description |
|---|---|---|
| username * | path | Public username. |
post/api/v1/contributions/import
Import an export or conversation as private draftsToken required
Supports ChatGPT, Claude, messages JSON/JSONL and archive record exports. Private drafts require individual review and consent before submission. Maximum file size 5 MiB and 200 conversations per import, subject to daily caps.
post/api/v1/drafts/{id}
Submit your reviewed draft for moderationToken required
| Parameter | Location | Description |
|---|---|---|
| id * | path | Lowercase public conversation ID returned as conversation_id or publicId. |
delete/api/v1/drafts/{id}
Delete your own unpublished draftToken required
| Parameter | Location | Description |
|---|---|---|
| id * | path | Lowercase public conversation ID returned as conversation_id or publicId. |
get/api/v1/openapi.json
Download this OpenAPI 3.1 contract