@mindthread/threads-api

March 22, 2026 · View on GitHub

English

Unofficial Threads API SDK for Node.js / TypeScript. Zero dependencies. Full API coverage.

Built and battle-tested by MindThread — powering 30+ automated Threads accounts with 900K+ total views.

Install

npm install @mindthread/threads-api

Quick Start

import { ThreadsClient, ThreadsAuth } from '@mindthread/threads-api'

const client = new ThreadsClient({
  userId: 'your-threads-user-id',
  accessToken: 'your-long-lived-token',
})

// Publish a text post
const post = await client.publish('Hello from Threads API!')
console.log('Published:', post.id)

// Publish an image post
await client.publishImage('Check this out!', 'https://example.com/image.jpg')

// Reply to a post
await client.reply(post.id, 'Thanks for reading!')

// Get post insights
const insights = await client.getInsights(post.id)
console.log(`${insights.views} views, ${insights.likes} likes`)

// Delete a post
await client.delete(post.id)

API Reference

`ThreadsClient`

Method	Description	Required Permission
`publish(text)`	Publish a text post	`threads_content_publish`
`publishImage(text, imageUrl)`	Publish an image post	`threads_content_publish`
`publishWithLocation(text, locationId)`	Publish with location tag	`threads_content_publish` + `threads_location_tagging`
`reply(replyToId, text)`	Reply to a post/comment	`threads_manage_replies`
`delete(postId)`	Delete a post	`threads_delete`
`getInsights(postId)`	Get post metrics	`threads_manage_insights`
`getProfile()`	Get your profile	`threads_basic`
`lookupUser(username)`	Find user by username	`threads_profile_discovery`
`getPublicProfile(userId)`	Get public profile	`threads_profile_discovery`
`getUserPosts(userId, limit?)`	Get user's posts	`threads_profile_discovery`
`search(query, options?)`	Search public posts	`threads_keyword_search`
`searchLocations(query, limit?)`	Search locations	`threads_location_tagging`
`getMentions(limit?)`	Get posts mentioning you	`threads_manage_mentions`

`ThreadsAuth` (Static Methods)

Method	Description
`exchangeCode(code, appId, appSecret, redirectUri)`	Exchange OAuth code for token
`exchangeForLongLived(shortToken, appSecret)`	Get 60-day long-lived token
`refreshToken(currentToken)`	Refresh before expiry

OAuth Flow

import { ThreadsAuth } from '@mindthread/threads-api'

// 1. User authorizes → you get a code
// 2. Exchange code for short-lived token
const { access_token, user_id } = await ThreadsAuth.exchangeCode(
  code, APP_ID, APP_SECRET, REDIRECT_URI
)

// 3. Exchange for long-lived token (60 days)
const longLived = await ThreadsAuth.exchangeForLongLived(access_token, APP_SECRET)

// 4. Refresh before expiry
const refreshed = await ThreadsAuth.refreshToken(longLived.access_token)

Search & Discovery

// Search public posts
const results = await client.search('typescript', {
  searchType: 'TOP',
  limit: 20,
})

// Look up a user
const userId = await client.lookupUser('zuck')
if (userId) {
  const profile = await client.getPublicProfile(userId)
  console.log(`@${profile.username}: ${profile.follower_count} followers`)
}

// Get mentions
const mentions = await client.getMentions()

Notes

Two-step publish: The Threads API requires a 3-second delay between creating a media container and publishing it. This SDK handles it automatically.
64-bit user IDs: Threads user IDs exceed Number.MAX_SAFE_INTEGER. This SDK extracts them as strings to prevent precision loss.
No dependencies: Uses native fetch (Node.js 18+).

繁體中文

非官方 Threads API SDK，支援 Node.js / TypeScript。零依賴。完整 API 覆蓋。

由 MindThread 開發並實戰驗證 — 驅動 30+ 個自動化 Threads 帳號，累計 900K+ 觀看數。

安裝

npm install @mindthread/threads-api

快速開始

import { ThreadsClient, ThreadsAuth } from '@mindthread/threads-api'

const client = new ThreadsClient({
  userId: '你的 Threads 用戶 ID',
  accessToken: '你的長期 Token',
})

// 發布文字貼文
const post = await client.publish('Hello from Threads API!')
console.log('已發布:', post.id)

// 發布圖片貼文
await client.publishImage('看看這個！', 'https://example.com/image.jpg')

// 回覆貼文
await client.reply(post.id, '感謝閱讀！')

// 取得貼文數據
const insights = await client.getInsights(post.id)
console.log(`${insights.views} 次觀看, ${insights.likes} 個讚`)

// 刪除貼文
await client.delete(post.id)

API 參考

`ThreadsClient`

方法	說明	需要的權限
`publish(text)`	發布文字貼文	`threads_content_publish`
`publishImage(text, imageUrl)`	發布圖片貼文	`threads_content_publish`
`publishWithLocation(text, locationId)`	帶地點標記發文	`threads_content_publish` + `threads_location_tagging`
`reply(replyToId, text)`	回覆貼文/留言	`threads_manage_replies`
`delete(postId)`	刪除貼文	`threads_delete`
`getInsights(postId)`	取得貼文數據	`threads_manage_insights`
`getProfile()`	取得自己的個人檔案	`threads_basic`
`lookupUser(username)`	用帳號名查詢用戶	`threads_profile_discovery`
`getPublicProfile(userId)`	取得公開個人檔案	`threads_profile_discovery`
`getUserPosts(userId, limit?)`	取得用戶的貼文	`threads_profile_discovery`
`search(query, options?)`	搜尋公開貼文	`threads_keyword_search`
`searchLocations(query, limit?)`	搜尋地點	`threads_location_tagging`
`getMentions(limit?)`	取得提及你的貼文	`threads_manage_mentions`

`ThreadsAuth`（靜態方法）

方法	說明
`exchangeCode(code, appId, appSecret, redirectUri)`	OAuth 授權碼換 Token
`exchangeForLongLived(shortToken, appSecret)`	換取 60 天長期 Token
`refreshToken(currentToken)`	到期前刷新 Token

OAuth 流程

import { ThreadsAuth } from '@mindthread/threads-api'

// 1. 用戶授權後，你會收到一個 code
// 2. 用 code 換短期 Token
const { access_token, user_id } = await ThreadsAuth.exchangeCode(
  code, APP_ID, APP_SECRET, REDIRECT_URI
)

// 3. 換取長期 Token（60 天有效）
const longLived = await ThreadsAuth.exchangeForLongLived(access_token, APP_SECRET)

// 4. 到期前刷新
const refreshed = await ThreadsAuth.refreshToken(longLived.access_token)

注意事項

兩步發文：Threads API 要求在建立草稿和發布之間等待 3 秒。本 SDK 已自動處理。
64 位元用戶 ID：Threads 的用戶 ID 超過 Number.MAX_SAFE_INTEGER。本 SDK 以字串形式提取，避免精度損失。
零依賴：使用原生 fetch（需 Node.js 18+）。

License

MIT - Made with pragmatism by MindThread