Talksearch

Quickstart

1
Create an account
Register, then open the developer dashboard.
2
Create and fund a key
Copy the key once and add prepaid crypto credit.
3
Send a request
Search the corpus or retrieve a post, topic, or profile by ID.

Authentication

Send your API key in the Authorization header. Keys begin with ts_live_, are displayed once, and can be revoked immediately from your dashboard.

Authorization: Bearer ts_live_your_key

The X-API-Key header is also supported. Never put a secret key in browser-delivered application code or a public repository.

Optional IP restrictions

Each key can be limited to individual IPv4 or IPv6 addresses and CIDR ranges, such as 203.0.113.10, 198.51.100.0/24, or 2001:db8::/32. Manage the allowlist from the developer dashboard. Requests from other addresses receive HTTP 403 before billing, with sourceIp showing the address TalkSearch detected.

Key expiration

Choose no expiration or a lifetime of 7, 30, 90, 180, or 365 days. An expired key receives HTTP 401 before billing. You can renew an expired key or change its expiration from the dashboard without replacing the secret.

GET/api/v1/search

Search indexed posts

Returns ranked post-level matches from the indexed Bitcointalk corpus. Search applies language-specific dictionaries, hybrid lexical/vector ranking, duplicate suppression, and quality filtering.

GET/api/v1/images/search

Search cached images

Find images through the text and metadata of the posts that contain them. Results are deduplicated by content and use stable cdn.talksearch.io URLs. Known forum smileys and high-confidence NSFW images are excluded by default.

Name	Type	Required	Description
`q`	string	Yes	Search query. Must contain between 1 and 512 characters.
`lang`	string	No	Language index to search, such as en, de, fr, or pt-BR.
`freshness`	string	No	Set to 1 to prefer newer posts. Omit it to use automatic freshness intent detection.
`include_low_quality`	string	No	Set to 1 to include replies normally removed by TalkSearch quality and spam filtering.
`size`	integer	No	Maximum unique images to return, from 1 to 50. Defaults to 24.
`hide_nsfw`	string	No	High-confidence NSFW images are hidden by default. Set to 0 to include them.

Retrieve corpus resources by ID

Use the numeric IDs from Bitcointalk URLs or TalkSearch results. A missing resource returns HTTP 404 and costs no credit.

GET

Post by ID

/api/v1/posts/{id}

Returns one indexed post with rendered HTML, author, board, topic, date, and merit observations.

Example ID: 34538660

GET

Topic by ID

/api/v1/topics/{id}

Returns topic metadata plus the complete first post and a summary of the latest indexed post.

Example ID: 3309245

GET

Profile by ID

/api/v1/profiles/{id}

Returns corpus-derived profile activity and recent posts for a Bitcointalk user ID.

Example ID: 1978649

Post-search parameters

Name	Type	Required	Description
`q`	string	Yes	Search query. Must contain between 1 and 512 characters.
`lang`	string	No	Language index to search, such as en, de, fr, or pt-BR.
`freshness`	string	No	Set to 1 to prefer newer posts. Omit it to use automatic freshness intent detection.
`include_low_quality`	string	No	Set to 1 to include replies normally removed by TalkSearch quality and spam filtering.

Request examples

Use an environment variable or server-side secret manager for production keys.

curl 'https://talksearch.io/api/v1/search?q=taproot+fee+estimation&lang=en' \
+  -H 'Authorization: Bearer ts_live_your_key'

Successful responses

Every response identifies its resource shape. The OpenAPI schema contains complete field definitions for code generation and validation.

Post search response

{
  "query": "taproot fee estimation",
  "corrected_query": null,
  "lang": "en",
  "board_scope": "strict-language-boards-v1",
  "index": "talksearch_posts_v3_en",
  "did_you_mean": null,
  "hybrid": true,
  "freshness": false,
  "answer_seeking": true,
  "total": 127,
  "hits": [
    {
      "post_id": 64551288,
      "topic_id": 5500892,
      "title": "When Taproot?",
      "topic_title": "When Taproot?",
      "post_title": "Re: When Taproot?",
      "content": "Example matching Bitcointalk post content.",
      "author": "ExampleUser",
      "author_uid": 3534730,
      "date": "2024-09-20T01:58:23.000Z",
      "board_id": 1,
      "board_name": "Bitcoin Discussion",
      "lang": "en",
      "score": 0.822709,
      "spam_score": 0,
      "ai_score": 0,
      "health_score": 1,
      "rank_source": "hybrid",
      "ranking_model_version": "relevance-authority-v5",
      "search_index": "talksearch_posts_v3_en"
    }
  ]
}

Image search response

{
  "object": "image_search",
  "query": "hardware wallet",
  "corrected_query": null,
  "lang": "en",
  "board_scope": "strict-language-boards-v1",
  "hide_nsfw": true,
  "post_matches_considered": 50,
  "total": 1,
  "images": [
    {
      "object": "image",
      "sha256": "53e2d1c2be8f2a0c87efbd85c73915b58344fd9a7f40b6eeb734f4014b5d0f07",
      "url": "https://cdn.talksearch.io/media/images/53e2d1c2be8f2a0c87efbd85c73915b58344fd9a7f40b6eeb734f4014b5d0f07.avif",
      "mime_type": "image/avif",
      "bytes": 48231,
      "nsfw_score": 0.01,
      "post": {
        "post_id": 64551288,
        "topic_id": 5500892,
        "title": "Hardware wallet comparison",
        "author": {
          "profile_id": 3534730,
          "username": "ExampleUser",
          "url": "https://bitcointalk.org/index.php?action=profile;u=3534730"
        },
        "board": {
          "board_id": 37,
          "name": "Hardware Wallets"
        },
        "language": "en",
        "posted_at": "2024-09-20T01:58:23.000Z",
        "url": "https://bitcointalk.org/index.php?topic=5500892.msg64551288#msg64551288",
        "topic_url": "https://bitcointalk.org/index.php?topic=5500892.0"
      }
    }
  ]
}

Post by ID response

{
  "object": "post",
  "post_id": 34538660,
  "topic_id": 3309245,
  "post_number": 1,
  "is_op": true,
  "title": "Forget about exchanger search! Use BestChange!",
  "author": {
    "profile_id": 1978649,
    "username": "Best.Change",
    "url": "https://bitcointalk.org/index.php?action=profile;u=1978649"
  },
  "board": {
    "board_id": 84,
    "name": "Service Announcements"
  },
  "language": "en",
  "posted_at": "2018-04-12T00:00:00.000Z",
  "url": "https://bitcointalk.org/index.php?topic=3309245.msg34538660#msg34538660",
  "topic_url": "https://bitcointalk.org/index.php?topic=3309245.0",
  "content_html": "<p>BestChange.com helps compare exchangers.</p>",
  "indexed_at": "2026-08-29T12:00:00.000Z",
  "merit": {
    "total": 0,
    "distinct_senders": 0,
    "transactions": 0,
    "observed_at": null
  }
}

Topic by ID response

{
  "object": "topic",
  "topic_id": 3309245,
  "title": "Forget about exchanger search! Use BestChange!",
  "board": {
    "board_id": 84,
    "name": "Service Announcements"
  },
  "language": "en",
  "created_at": "2018-04-12T00:00:00.000Z",
  "last_post_at": "2026-08-29T00:00:00.000Z",
  "post_count": 2400,
  "page_count": 120,
  "views": {
    "observed": 100000,
    "observed_at": "2026-08-29T00:00:00.000Z"
  },
  "merit": {
    "total": 400,
    "distinct_senders": 120,
    "transactions": 200,
    "observed_at": "2026-08-29T00:00:00.000Z"
  },
  "url": "https://bitcointalk.org/index.php?topic=3309245.0",
  "first_post": {
    "object": "post",
    "post_id": 34538660,
    "topic_id": 3309245,
    "post_number": 1,
    "is_op": true,
    "title": "Forget about exchanger search! Use BestChange!",
    "author": {
      "profile_id": 1978649,
      "username": "Best.Change",
      "url": "https://bitcointalk.org/index.php?action=profile;u=1978649"
    },
    "board": {
      "board_id": 84,
      "name": "Service Announcements"
    },
    "language": "en",
    "posted_at": "2018-04-12T00:00:00.000Z",
    "url": "https://bitcointalk.org/index.php?topic=3309245.msg34538660#msg34538660",
    "topic_url": "https://bitcointalk.org/index.php?topic=3309245.0",
    "content_html": "<p>BestChange.com helps compare exchangers.</p>",
    "indexed_at": "2026-08-29T12:00:00.000Z",
    "merit": {
      "total": 0,
      "distinct_senders": 0,
      "transactions": 0,
      "observed_at": null
    }
  },
  "latest_post": {
    "post_id": 67000000,
    "topic_id": 3309245,
    "post_number": 2400,
    "is_op": false,
    "title": "Forget about exchanger search! Use BestChange!",
    "author": {
      "profile_id": 1978649,
      "username": "Best.Change",
      "url": "https://bitcointalk.org/index.php?action=profile;u=1978649"
    },
    "board": {
      "board_id": 84,
      "name": "Service Announcements"
    },
    "language": "en",
    "posted_at": "2026-08-29T00:00:00.000Z",
    "url": "https://bitcointalk.org/index.php?topic=3309245.msg67000000#msg67000000",
    "topic_url": "https://bitcointalk.org/index.php?topic=3309245.0"
  }
}

Profile by ID response

{
  "object": "profile",
  "profile_id": 1978649,
  "username": "Best.Change",
  "url": "https://bitcointalk.org/index.php?action=profile;u=1978649",
  "corpus": {
    "post_count": 1200,
    "topic_count": 18,
    "first_post_at": "2017-11-01T00:00:00.000Z",
    "last_post_at": "2026-08-29T00:00:00.000Z",
    "derived_from": "distinct indexed posts"
  },
  "recent_posts": [
    {
      "post_id": 67000000,
      "topic_id": 3309245,
      "post_number": 2400,
      "is_op": false,
      "title": "Forget about exchanger search! Use BestChange!",
      "author": {
        "profile_id": 1978649,
        "username": "Best.Change",
        "url": "https://bitcointalk.org/index.php?action=profile;u=1978649"
      },
      "board": {
        "board_id": 84,
        "name": "Service Announcements"
      },
      "language": "en",
      "posted_at": "2026-08-29T00:00:00.000Z",
      "url": "https://bitcointalk.org/index.php?topic=3309245.msg67000000#msg67000000",
      "topic_url": "https://bitcointalk.org/index.php?topic=3309245.0"
    }
  ]
}

Try it

Send a real request without leaving the documentation. Your key stays in this page’s memory and is sent only to the same-origin TalkSearch API.

ResponseWaiting for a request

Choose an operation, enter a revocable API key, and inspect the live JSON response and metering headers.

Errors

HTTP	Meaning	What to do
400	A query, language code, result size, or resource ID is invalid.	Correct the request parameters and retry.
401	The API key is missing, invalid, expired, or revoked.	Use an active key or renew an expired key from the developer dashboard.
402	The account has insufficient prepaid credits.	Top up the account before retrying.
403	The source IP is not allowed for this API key.	Add the returned sourceIp to the key allowlist, or send the request from an allowed address.
404	The requested post, topic, or profile is not in the indexed corpus.	Check the Bitcointalk ID. Not-found lookups are not charged.
429	The API-key rate limit was exceeded.	Wait until X-RateLimit-Reset, then retry with backoff.
503	The requested operation could not complete.	Retry later. The failed request is not charged.

Metering and limits

One credit per success

A completed search or returned resource charges one credit. Invalid IDs, not-found resources, and service failures are not charged.

120 requests per minute

The limit applies per API key. Use the X-RateLimit-* response headers to schedule retries.

Successful responses also return X-Request-Id, X-Credits-Charged, and X-Credits-Remaining.

Bitcointalk data, ready for code.