Pickful API Integration Guide | 6.19

---

Hey Pickful community,

We’re releasing a complete API integration guide to help developers and creators seamlessly publish to Pickful through code and automation.

---

Get Started in 3 Steps

Step 1: Create an API Token

Visit https://pickful.ai/api_tokens to create a new token

• Format: pkfl_live_<random> (shown once—keep it safe!)
• Scope: Select posts:write
• Expiry: Never (revoke anytime you want)

Step 2: Send a Request

curl -X POST https://pickful.ai/api/posts \
  -H "Authorization: Bearer pkfl_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Article",
    "content": "Article content in **markdown** format",
    "topic_id": "t5a"
  }'

Step 3: Handle the Response

{
  "id": 12345,
  "slug": "abc12",
  "post_type": "article",
  "url": "https://pickful.ai/p-abc12",
  "created_at": "2026-06-17T10:30:00Z"
}

---

API Reference

Endpoint

POST /api/posts

Authentication

Authorization: Bearer <api_token>

Request Parameters

Parameter	Type	Description
content	string	Article content (Markdown format). Content alone creates a post; with title, creates an article
title	string	Article title. Presence auto-sets post type to “article”
summary	string	Article summary (optional)
topic_id	string	Topic ID (e.g., t5a)
source	string	Source attribution for tracking
published_at	string	Publish time (ISO8601). Blank = publish now; future time = schedule
image_url	string	Image URL (use either this or image_base64)
image_base64	string	Base64-encoded image
image_filename	string	Filename for the image (optional)
image_content_type	string	Image MIME type: image/png, image/jpeg, image/webp
x	boolean	Post to X? (default: false)
tweets	array	X thread text (optional)

Response Status Codes

Code	Meaning
201	Created successfully
401	Unauthorized (invalid or missing token)
403	Forbidden (missing posts:write scope)
422	Unprocessable (validation failed)

---

Common Use Cases

Post a Short Message

{
  "content": "This is a short post 🚀"
}

Publish an Article

{
  "title": "Deep Dive: How DeFi Works",
  "content": "# Introduction\n\nDeFi stands for...",
  "summary": "A comprehensive guide to DeFi",
  "topic_id": "t5a"
}

Article with Image

From URL:

{
  "title": "Product Launch",
  "content": "We're excited to announce...",
  "image_url": "https://example.com/image.jpg"
}

From Base64:

{
  "title": "Quick Update",
  "content": "Check out our new feature!",
  "image_base64": "iVBORw0KGgoAAAAN...",
  "image_content_type": "image/png"
}

Schedule a Post

{
  "title": "Scheduled Article",
  "content": "This publishes later",
  "published_at": "2026-06-18T09:00:00Z"
}

Publish to X

Auto-generate tweet text:

{
  "title": "My Latest Article",
  "content": "Full article content...",
  "x": true
}

Custom thread (multiple tweets):

{
  "title": "3-Tweet Thread",
  "content": "Main article...",
  "x": true,
  "tweets": [
    "First tweet text",
    "Second tweet text",
    "Third tweet text"
  ]
}

---

Image Requirements

Supported Formats

• PNG (image/png)
• JPEG (image/jpeg)
• WebP (image/webp)

Size Limit

• Maximum 5MB

Usage

• Articles: Image serves as cover, displayed at top
• Posts: Image embedded inline in content

---

Markdown Support

# Heading 1
## Heading 2

**bold** and *italic*

- Bullet list
- Bullet list

1. Numbered list
2. Numbered list


[Link](https://example.com)

`code` and ```code block```

---

Error Handling

Error	Cause	Solution
401 Unauthorized	Invalid or missing token	Check token format and expiry
403 Forbidden	Missing posts:write scope	Create token with correct permissions
422 - Content can’t be blank	No content provided	Provide either content or title
422 - invalid_published_at	Bad datetime format	Use ISO8601; must be future time
invalid_image	Image format or size issue	Check format (PNG/JPEG/WebP) and size (<5MB)

---

Code Examples

Python

import requests
import os

API_TOKEN = os.environ.get("PICKFUL_API_TOKEN")
API_URL = "https://pickful.ai/api/posts"

def publish_article(title, content, topic_id="t5a"):
    headers = {
        "Authorization": f"Bearer {API_TOKEN}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "title": title,
        "content": content,
        "topic_id": topic_id
    }
    
    response = requests.post(API_URL, json=payload, headers=headers)
    
    if response.status_code == 201:
        return response.json()
    else:
        print(f"Error {response.status_code}: {response.text}")
        return None

# Usage
result = publish_article("My First Article", "Article content...")
if result:
    print(f"Published: {result['url']}")

JavaScript

const fetch = require('node-fetch');

const API_TOKEN = process.env.PICKFUL_API_TOKEN;
const API_URL = 'https://pickful.ai/api/posts';

async function publishArticle(title, content, topicId = 't5a') {
  try {
    const response = await fetch(API_URL, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        title,
        content,
        topic_id: topicId
      })
    });

    if (response.ok) {
      const data = await response.json();
      return data;
    } else {
      console.error(`Error ${response.status}`);
      return null;
    }
  } catch (error) {
    console.error('Request failed:', error);
    return null;
  }
}

publishArticle('My Article', 'Content...').then(result => {
  if (result) console.log(`Published: ${result.url}`);
});

---

Security Best Practices

1. Protect your token
   • Never hardcode it in code
   • Use env var: PICKFUL_API_TOKEN
   • Revoke and recreate if leaked
2. Validate requests
   • Always use HTTPS
   • Check response status codes
3. Handle errors
   • Implement retry logic (exponential backoff)
   • Log errors for debugging

---

Combine with Claude CLI

Leverage your existing Claude subscription to automate the entire workflow:

# Use Claude to generate a summary, then publish via API
claude -p "Generate a 50-character summary for: [your article]"

---

We’ve got everything ready. Create a token now and start building! Questions? Ask the community.

Pickful Team
June 17, 2026