@mindthread/threads-api

English | 繁體中文

---

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