---
slug: "threads-api-skill"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/madebypan/threads-api-skill@main/README.md"
repo: "https://github.com/madebypan/threads-api-skill"
source_file: "README.md"
branch: "main"
---
# Threads API Skill for Claude Code

A complete, battle-tested guide and toolkit for publishing to Meta Threads via API — packaged as a [Claude Code Skill](https://docs.anthropic.com/en/docs/claude-code/skills).

> Includes setup flow, multi-post threading with images, executable scripts, and Chrome automation guides for AI-driven workflows.

---

## Features

- **Full setup flow** — from creating a Meta App to obtaining a long-lived token (60-day)
- **Multi-post threads** — chain posts with `reply_to_id`, mix text and images
- **Image support** — upload to public URL (catbox.moe) + attach via `image_url`
- **Executable script** — `post-thread.sh` ready to use with `.env` credentials
- **Chrome automation guides** — for both Claude Code and OpenAI Codex
- **Pitfall documentation** — 10+ real pitfalls encountered and documented at each step

---

## Quick Start

### 1. Clone and configure

```bash
git clone https://github.com/PRODUCTIVITYENHANCE/threads-api-skill.git
cd threads-api-skill

# Copy and fill in your credentials
cp .env.example .env
# Edit .env with your THREADS_APP_ID, THREADS_APP_SECRET, THREADS_USER_ID, THREADS_ACCESS_TOKEN
```

### 2. Post a thread

```bash
# Edit content in post-thread.sh, then:
chmod +x post-thread.sh
./post-thread.sh
```

### 3. Use as Claude Code Skill

Copy the `.claude/skills/threads-api/` folder into your project:

```bash
cp -r .claude/skills/threads-api/ YOUR_PROJECT/.claude/skills/threads-api/
```

Then invoke in Claude Code:

```
/threads-api
```

---

## File Structure

```
.
├── README.md
├── .env.example              ← Credential template
├── post-thread.sh            ← Executable posting script
└── .claude/skills/threads-api/
    ├── SKILL.md              ← Skill entry point
    ├── setup.md              ← Full setup flow + 10 pitfalls
    ├── post-thread.md        ← Thread posting guide + 7 pitfalls
    ├── post-thread.sh        ← Script (also in skill folder)
    ├── chrome-setup-claude.md ← Claude Code × Chrome guide
    └── chrome-setup-codex.md  ← Codex × Chrome guide
```

---

## Threads API Overview

### Authentication Flow

```
Create Meta App → Add Tester → Accept Invitation
→ Graph API Explorer (switch to .threads.net/)
→ Generate Short-lived Token (1 hour)
→ Exchange for Long-lived Token (60 days)
```

### Publishing Flow

```
Create Container (text/image) → Wait 30s → Publish
                                              ↓
Create Reply Container (reply_to_id) → Wait 30s → Publish
```

### Key Endpoints

| Action | Method | Endpoint |
|--------|--------|----------|
| Create container | POST | `/{user_id}/threads` |
| Publish | POST | `/{user_id}/threads_publish` |
| Refresh token | GET | `/refresh_access_token` |

---

## Critical Pitfalls

These are real issues encountered during development — not hypothetical:

| # | Pitfall | Solution |
|---|---------|----------|
| 1 | Graph API Explorer defaults to `.facebook.com/` | **Must** switch API selector to `.threads.net/` |
| 2 | "Generate Token" button missing | Switch API selector first — button only appears for Threads API |
| 3 | Image URL must be publicly accessible | Use catbox.moe (free, no signup); 0x0.st is dead |
| 4 | Container publish fails immediately | Wait 30 seconds between create and publish |
| 5 | Token expires silently | Long-lived token = 60 days; set a reminder to refresh |

See [setup.md](https://github.com/madebypan/threads-api-skill/blob/HEAD/.claude/skills/threads-api/setup.md) and [post-thread.md](https://github.com/madebypan/threads-api-skill/blob/HEAD/.claude/skills/threads-api/post-thread.md) for the full list.

---

## Chrome Automation (for AI agents)

This project includes guides for letting AI tools operate Chrome to handle login-gated steps (Meta Developer Console, Graph API Explorer):

- **Claude Code** → [`chrome-setup-claude.md`](https://github.com/madebypan/threads-api-skill/blob/HEAD/.claude/skills/threads-api/chrome-setup-claude.md)
- **OpenAI Codex** → [`chrome-setup-codex.md`](https://github.com/madebypan/threads-api-skill/blob/HEAD/.claude/skills/threads-api/chrome-setup-codex.md)

---

## Token Management

```bash
# Refresh before expiry (within the 60-day window):
curl "https://graph.threads.net/refresh_access_token?grant_type=th_refresh_token&access_token=YOUR_TOKEN"
```

---

## License

MIT