Skip to content
The Chat Archive
Developers · API v1

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/v1
Public reads are free and need no API key. Only approved public content is returned. Each record has its own license and attribution; a catalog entry does not mean its records are hosted here.

Quickstart

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/stats

Authentication & contributions

  1. Sign in with Google, GitHub, or email, then open Settings → API tokens.
  2. Create a labelled personal token. Copy it when shown; only its hash is stored.
  3. Keep the token in your server’s environment and send Authorization: Bearer YOUR_TOKEN. Never embed a personal token in a public app.
  4. 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-After before retrying. Handle errors by error.code; the message is for people.
  • Responses include X-API-Version and X-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

ParameterLocationDescription
qqueryKeyword search in prompts and responses; max 200 characters.
modequerySemantic mode falls back to keyword search with a notice when unavailable.
providerqueryProvider slug.
modelqueryModel slug.
tagqueryTopic slug.
languagequeryLanguage code, for example en.
sourcequerySource type. Fixtures appear only in development and remain labelled.
datasetqueryExternal source-catalog slug.
minTurnsqueryMinimum user turns.
maxTurnsqueryMaximum user turns.
minScorequeryMinimum community score.
fromqueryPublished on or after YYYY-MM-DD.
toqueryPublished on or before YYYY-MM-DD.
correctionsqueryOnly conversations with a user correction.
evaluatedqueryOnly conversations with verified evaluation.
sortqueryBrowse defaults to recent; keyword search defaults to relevance.
cursorqueryOpaque next_cursor from the previous response. Keep all other filters unchanged.
limitqueryResults 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

ParameterLocationDescription
qqueryKeyword search in prompts and responses; max 200 characters.
modequerySemantic mode falls back to keyword search with a notice when unavailable.
providerqueryProvider slug.
modelqueryModel slug.
tagqueryTopic slug.
languagequeryLanguage code, for example en.
sourcequerySource type. Fixtures appear only in development and remain labelled.
datasetqueryExternal source-catalog slug.
minTurnsqueryMinimum user turns.
maxTurnsqueryMaximum user turns.
minScorequeryMinimum community score.
fromqueryPublished on or after YYYY-MM-DD.
toqueryPublished on or before YYYY-MM-DD.
correctionsqueryOnly conversations with a user correction.
evaluatedqueryOnly conversations with verified evaluation.
sortqueryBrowse defaults to recent; keyword search defaults to relevance.
cursorqueryOpaque next_cursor from the previous response. Keep all other filters unchanged.
limitqueryResults per page.

get/api/v1/conversations/{id}

Read an approved conversation, messages, attribution and license

ParameterLocationDescription
id *pathLowercase public conversation ID returned as conversation_id or publicId.

get/api/v1/conversations/{id}/download

Download one approved conversation as JSON

ParameterLocationDescription
id *pathLowercase 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

ParameterLocationDescription
windowqueryLeaderboard time window.
tagqueryOptional topic slug.
limitqueryMaximum 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

ParameterLocationDescription
slug *pathSource 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

ParameterLocationDescription
version *pathPublished 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.

ParameterLocationDescription
version *pathPublished release version, for example v0.1. Never use a source-catalog slug here.
path *pathRelative manifest file path, such as community/community-00000.parquet.

get/api/v1/users/{username}

Public profile without email, internal IDs or anonymous contribution links

ParameterLocationDescription
username *pathPublic 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

ParameterLocationDescription
id *pathLowercase public conversation ID returned as conversation_id or publicId.

delete/api/v1/drafts/{id}

Delete your own unpublished draftToken required

ParameterLocationDescription
id *pathLowercase public conversation ID returned as conversation_id or publicId.

get/api/v1/openapi.json

Download this OpenAPI 3.1 contract