threads-api

What this skill does

# Threads API Skill

Comprehensive assistance with Meta's Threads API development for building applications that integrate with the Threads social platform.

## When to Use This Skill

This skill should be triggered when you are:
- **Building Threads integrations** - Creating apps that post to or read from Threads
- **Implementing authentication** - Setting up OAuth flows for Threads API access
- **Working with media uploads** - Uploading images, videos, or carousel posts to Threads
- **Managing user content** - Publishing, retrieving, or managing Threads posts
- **Fetching analytics** - Retrieving insights and metrics for Threads content
- **Handling webhooks** - Processing real-time updates from Threads
- **Troubleshooting API errors** - Debugging authentication, rate limits, or API responses
- **Reading Threads profiles** - Fetching user profile data and posts

## Quick Reference

### Authentication - Getting an Access Token

```javascript
// Step 1: Redirect user to authorization endpoint
const authUrl = `https://threads.net/oauth/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&scope=threads_basic,threads_content_publish&response_type=code`;

// Step 2: Exchange authorization code for access token
const response = await fetch('https://graph.threads.net/oauth/access_token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    grant_type: 'authorization_code',
    redirect_uri: REDIRECT_URI,
    code: authorizationCode
  })
});

const { access_token } = await response.json();
```

### Publishing a Text Post

```javascript
// Create a simple text post
const response = await fetch(`https://graph.threads.net/v1.0/me/threads`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    media_type: 'TEXT',
    text: 'Hello from Threads API! 🎉'
  })
});

const data = await response.json();
console.log('Post ID:', data.id);
```

### Publishing an Image Post

```python
import requests

# Upload and publish an image
url = "https://graph.threads.net/v1.0/me/threads"
headers = {"Authorization": f"Bearer {access_token}"}

data = {
    "media_type": "IMAGE",
    "image_url": "https://example.com/image.jpg",
    "text": "Check out this image! #API"
}

response = requests.post(url, headers=headers, json=data)
post_id = response.json()["id"]
print(f"Posted image with ID: {post_id}")
```

### Publishing a Video Post

```javascript
// Step 1: Create a video container
const container = await fetch(`https://graph.threads.net/v1.0/me/threads`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}` },
  body: JSON.stringify({
    media_type: 'VIDEO',
    video_url: 'https://example.com/video.mp4',
    text: 'Check out this video!'
  })
});

const { id: containerId } = await container.json();

// Step 2: Publish the container
await fetch(`https://graph.threads.net/v1.0/me/threads_publish`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}` },
  body: JSON.stringify({ creation_id: containerId })
});
```

### Fetching User Profile

```python
import requests

# Get authenticated user's profile
url = f"https://graph.threads.net/v1.0/me"
headers = {"Authorization": f"Bearer {access_token}"}
params = {
    "fields": "id,username,name,threads_profile_picture_url,threads_biography"
}

response = requests.get(url, headers=headers, params=params)
profile = response.json()

print(f"Username: {profile['username']}")
print(f"Bio: {profile['threads_biography']}")
```

### Fetching User's Threads

```javascript
// Get user's recent threads with pagination
const response = await fetch(
  `https://graph.threads.net/v1.0/me/threads?fields=id,text,timestamp,media_url&limit=25`,
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
);

const { data, paging } = await response.json();
data.forEach(thread => {
  console.log(`${thread.timestamp}: ${thread.text}`);
});

// Use paging.next for next page
```

### Publishing a Carousel Post

```python
import requests

# Create a carousel with multiple images
url = "https://graph.threads.net/v1.0/me/threads"
headers = {"Authorization": f"Bearer {access_token}"}

data = {
    "media_type": "CAROUSEL",
    "children": [
        {"media_type": "IMAGE", "image_url": "https://example.com/img1.jpg"},
        {"media_type": "IMAGE", "image_url": "https://example.com/img2.jpg"},
        {"media_type": "IMAGE", "image_url": "https://example.com/img3.jpg"}
    ],
    "text": "Swipe through these images! 📸"
}

response = requests.post(url, headers=headers, json=data)
carousel_id = response.json()["id"]
```

### Retrieving Insights (Analytics)

```javascript
// Get insights for a specific thread
const threadId = '123456789';
const response = await fetch(
  `https://graph.threads.net/v1.0/${threadId}/insights?metric=views,likes,replies,reposts`,
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
);

const { data } = await response.json();
data.forEach(metric => {
  console.log(`${metric.name}: ${metric.values[0].value}`);
});
```

### Error Handling Pattern

```python
import requests

def make_threads_request(url, access_token, method='GET', **kwargs):
    """Robust error handling for Threads API requests"""
    headers = kwargs.pop('headers', {})
    headers['Authorization'] = f"Bearer {access_token}"

    try:
        response = requests.request(method, url, headers=headers, **kwargs)
        response.raise_for_status()
        return response.json()

    except requests.exceptions.HTTPError as e:
        error_data = e.response.json()
        error_code = error_data.get('error', {}).get('code')
        error_msg = error_data.get('error', {}).get('message')

        if error_code == 190:
            raise Exception(f"Invalid access token: {error_msg}")
        elif error_code == 32:
            raise Exception(f"Rate limit exceeded: {error_msg}")
        else:
            raise Exception(f"API Error {error_code}: {error_msg}")

    except requests.exceptions.RequestException as e:
        raise Exception(f"Network error: {str(e)}")
```

## Key Concepts

### Access Tokens and Permissions
- **Access Tokens**: OAuth 2.0 tokens required for all API requests
- **Scopes**: Define what your app can access (e.g., `threads_basic`, `threads_content_publish`, `threads_manage_insights`)
- **Token Expiration**: Long-lived tokens (60 days) and refresh tokens for extended access

### Media Types
- **TEXT**: Simple text posts
- **IMAGE**: Single image with optional caption
- **VIDEO**: Single video with optional caption
- **CAROUSEL**: Multiple images or videos in a swipeable format

### Publishing Flow
1. **Container Creation**: Create a media container with content
2. **Publishing**: Publish the container to make it visible
3. **Two-stage process**: Required for videos and carousels to allow processing time

### Rate Limits
- Rate limits vary by endpoint and access level
- Standard rate limit: 200 calls per hour per user
- Monitor `X-Business-Use-Case-Usage` header in responses
- Implement exponential backoff for rate limit errors

### Webhooks
- Real-time notifications for events like mentions, replies, or new followers
- Requires HTTPS endpoint for receiving notifications
- Must validate webhook signatures for security

## Reference Files

This skill includes comprehensive documentation in `references/`:

- **other.md** - Complete Threads API documentation including:
  - Authentication and authorization flows
  - API endpoints reference
  - Request/response formats
  - Error codes and troubleshooting
  - Best practices and guidelines

Use the skill's reference files when you need detailed information about specific API endpoints, parameters, or advanced features.

## Working with This Skill

### For Beginners
Start by understanding the authentication flow - this is the