Threads API

--- name: Threads API description: Use when you need to publish content, manage posts, retrieve media, or interact with Meta's Threads platform programmatically. Essential for social media automation, content publishing workflows, and Threads integration projects. metadata: author: skynet version: 1.0.0 category: social --- # Threads API Skill ## Overview The Threads API allows developers to publish text posts, retrieve media, manage user content, and interact with Meta's Threads platform programmatically. ## Prerequisites - Meta for Developers account - Valid access token with appropriate permissions - App configured for Threads API access ## Authentication Setup ### Get Access Token ```bash # Exchange authorization code for access token curl -X POST "https://graph.threads.net/oauth/access_token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=YOUR_APP_ID" \ -d "client_secret=YOUR_APP_SECRET" \ -d "grant_type=authorization_code" \ -d "redirect_uri=YOUR_REDIRECT_URI" \ -d "code=AUTHORIZATION_CODE" ``` ### Refresh Long-Lived Token ```bash curl -X GET "https://graph.threads.net/refresh_access_token?grant_type=th_refresh_token&refresh_token=REFRESH_TOKEN" ``` ## Core Operations ### Publishing Content #### Create Text Post ```bash # Step 1: Create media container curl -X POST "https://graph.threads.net/v1.0/me/threads" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -d "media_type=TEXT" \ -d "text=Your post content here #hashtag" # Step 2: Publish the container curl -X POST "https://graph.threads.net/v1.0/me/threads_publish" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -d "creation_id=CONTAINER_ID" ``` #### Create Image Post ```bash # Create image post container curl -X POST "https://graph.threads.net/v1.0/me/threads" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -d "media_type=IMAGE" \ -d "image_url=https://example.com/image.jpg" \ -d "text=Caption for your image" # Publish the image post curl -X POST "https://graph.threads.net/v1.0/me/threads_publish" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -d "creation_id=CONTAINER_ID" ``` #### Create Video Post ```bash curl -X POST "https://graph.threads.net/v1.0/me/threads" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -d "media_type=VIDEO" \ -d "video_url=https://example.com/video.mp4" \ -d "text=Video caption text" ``` ### Retrieving Content #### Get User's Threads ```bash curl -X GET "https://graph.threads.net/v1.0/me/threads?fields=id,media_type,media_url,permalink,text,timestamp,username" \ -H "Authorization: Bearer ACCESS_TOKEN" ``` #### Get Specific Thread Details ```bash curl -X GET "https://graph.threads.net/v1.0/THREAD_ID?fields=id,media_type,media_url,permalink,text,timestamp,username,is_quote_post" \ -H "Authorization: Bearer ACCESS_TOKEN" ``` #### Get User Profile ```bash curl -X GET "https://graph.threads.net/v1.0/me?fields=id,username,threads_profile_picture_url,threads_biography" \ -H "Authorization: Bearer ACCESS_TOKEN" ``` ## Advanced Workflows ### Content Publishing Decision Tree ``` Content Type? ├── Text Only │ └── Create TEXT container → Publish ├── Image + Text │ ├── Image < 8MB? → Create IMAGE container → Publish │ └── Image > 8MB? → Compress first → Retry └── Video + Text ├── Video < 100MB & < 60s? → Create VIDEO container → Publish └── Video too large? → Process video → Retry ``` ### Batch Content Publishing ```bash #!/bin/bash # Batch publish script ACCESS_TOKEN="your_access_token" POSTS_FILE="posts.txt" while IFS= read -r post_text; do # Create container CONTAINER_ID=$(curl -s -X POST "https://graph.threads.net/v1.0/me/threads" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -d "media_type=TEXT" \ -d "text=$post_text" | jq -r '.id') # Wait before publishing sleep 2 # Publish post curl -X POST "https://graph.threads.net/v1.0/me/threads_publish" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -d "creation_id=$CONTAINER_ID" # Rate limit protection sleep 10 done < "$POSTS_FILE" ``` ### Media Upload with Validation ```python import requests import time def publish_thread_with_media(access_token, media_url, text, media_type="IMAGE"): # Step 1: Create container container_data = { "media_type": media_type, f"{media_type.lower()}_url": media_url, "text": text } container_response = requests.post( f"https://graph.threads.net/v1.0/me/threads", headers={"Authorization": f"Bearer {access_token}"}, data=container_data ) if container_response.status_code != 200: return {"error": container_response.json()} container_id = container_response.json()["id"] # Step 2: Wait for processing time.sleep(5) # Step 3: Publish publish_response = requests.post( f"https://graph.threads.net/v1.0/me/threads_publish", headers={"Authorization": f"Bearer {access_token}"}, data={"creation_id": container_id} ) return publish_response.json() ``` ## Rate Limiting & Best Practices ### Rate Limit Headers ```bash # Check rate limit status curl -I -X GET "https://graph.threads.net/v1.0/me/threads" \ -H "Authorization: Bearer ACCESS_TOKEN" # Look for these headers: # X-Business-Use-Case-Usage # X-App-Usage ``` ### Handling Rate Limits ```bash #!/bin/bash check_rate_limit() { RESPONSE=$(curl -s -I -X GET "https://graph.threads.net/v1.0/me" \ -H "Authorization: Bearer $ACCESS_TOKEN") if echo "$RESPONSE" | grep -q "429"; then echo "Rate limited. Waiting 60 seconds..." sleep 60 return 1 fi return 0 } ``` ## Error Handling ### Common Error Responses #### Invalid Access Token ```json { "error": { "message": "Invalid OAuth access token.", "type": "OAuthException", "code": 190 } } ``` **Fix**: Refresh your access token or re-authenticate #### Media Upload Failed ```json { "error": { "message": "Media could not be processed", "type": "ThreadsAPIException", "code": 9001 } } ``` **Fix**: Check media format, size limits, and URL accessibility #### Publishing Too Fast ```json { "error": { "message": "Application request limit reached", "type": "ThreadsAPIException", "code": 4 } } ``` **Fix**: Implement delays between requests (minimum 10 seconds) ### Debugging Script ```bash #!/bin/bash debug_threads_api() { local response=$(curl -s -w "%{http_code}" -X GET "https://graph.threads.net/v1.0/me" \ -H "Authorization: Bearer $ACCESS_TOKEN") local http_code="${response: -3}" local body="${response%???}" case $http_code in 200) echo "✅ API connection successful" ;; 400) echo "❌ Bad request: $body" ;; 401) echo "❌ Unauthorized - check access token" ;; 403) echo "❌ Forbidden - check permissions" ;; 429) echo "⚠️ Rate limited" ;; 500) echo "❌ Server error" ;; *) echo "❌ Unknown error: $http_code" ;; esac } ``` ## Monitoring & Analytics ### Track Post Performance ```bash # Get post metrics curl -X GET "https://graph.threads.net/v1.0/THREAD_ID?fields=id,text,timestamp,like_count,reply_count,repost_count,quote_count" \ -H "Authorization: Bearer ACCESS_TOKEN" ``` ### Webhook Setup for Real-time Updates ```bash # Configure webhook curl -X POST "https://graph.threads.net/v1.0/APP_ID/subscriptions" \ -H "Authorization: Bearer APP_ACCESS_TOKEN" \ -d "object=threads" \ -d "callback_url=https://yourserver.com/webhook" \ -d "fields=mentions,replies" \ -d "verify_token=your_verify_token" ``` ## Content Validation ### Pre-publish Checklist ```bash validate_content() { local text="$1" local media_url="$2" # Check text length (500 char limit) if [ ${#text} -gt 500 ]; then echo "❌ Text too long (${#text}/500 chars)" return 1 fi # Validate media URL if provided if [ -n "$media_url" ]; then if ! curl -sf "$media_url" > /dev/null; then echo "❌ Media URL inaccessible" return 1 fi fi echo "✅ Content validation passed" return 0 } ```