Skip to main content

Building AI Agents

Use the PostEverywhere API to give your AI agent the ability to schedule and publish social media posts across 8 platforms.

Quick Reference for Agents​

Your agent needs these endpoints:

ActionMethodEndpointDescription
List accountsGET/api/v1/accountsGet connected social accounts and their IDs
Create a postPOST/api/v1/postsCreate, schedule, or immediately publish a post
Check resultsGET/api/v1/posts/{id}/resultsSee per-platform publish status
Retry failuresPOST/api/v1/posts/{id}/retryRetry failed platform destinations
Upload mediaPOST/api/v1/media/uploadGet presigned URL for image/video upload
List postsGET/api/v1/postsList existing posts with status filter

Base URL: https://app.posteverywhere.ai/api/v1

Authentication: Authorization: Bearer pe_live_<your-key>

Common Mistakes
  • The endpoint to create a post is /api/v1/posts, NOT /api/v1/publish
  • There is no /api/v1/schedule endpoint - use POST /api/v1/posts with a scheduled_at field
  • Account IDs are integers (e.g. 2280), not platform usernames
  • All dates must be ISO 8601 format with timezone (e.g. 2026-04-01T10:00:00Z)

Step-by-Step Agent Flow​

1. Get account IDs​

import requests

API_KEY = "pe_live_..."
BASE = "https://app.posteverywhere.ai/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# List connected accounts
accounts = requests.get(f"{BASE}/accounts", headers=headers).json()

for acc in accounts["data"]["accounts"]:
    print(f"{acc['platform']}: {acc['account_name']} (ID: {acc['id']})")

2. Create and publish a post​

# Post immediately to specific accounts
post = requests.post(f"{BASE}/posts", headers=headers, json={
    "content": "Posted by my AI agent!",
    "account_ids": [2280, 2281],  # Instagram + X account IDs
}).json()

print(f"Post ID: {post['data']['post_id']}")
print(f"Status: {post['data']['status']}")  # 'publishing' for immediate

3. Schedule a post for later​

# Schedule for tomorrow at 10am UTC
post = requests.post(f"{BASE}/posts", headers=headers, json={
    "content": "Scheduled by my AI agent!",
    "account_ids": [2280],
    "scheduled_at": "2026-04-03T10:00:00Z",
    "timezone": "America/New_York"  # optional, defaults to UTC
}).json()

print(f"Status: {post['data']['status']}")  # 'scheduled'

4. Check publish results​

# Check per-platform results
post_id = post["data"]["post_id"]
results = requests.get(f"{BASE}/posts/{post_id}/results", headers=headers).json()

for dest in results["data"]["results"]:
    print(f"{dest['platform']}: {dest['status']} - {dest.get('platform_post_url', 'pending')}")

5. Retry failed platforms​

# If any platform failed, retry it
retry = requests.post(f"{BASE}/posts/{post_id}/retry", headers=headers).json()
print(f"Retried: {retry['data']['retried_count']} destinations")

Platform-Specific Content​

Customize content per platform using platform_content:

post = requests.post(f"{BASE}/posts", headers=headers, json={
    "content": "Default content for all platforms",
    "account_ids": [2280, 2281, 2282],  # Instagram, X, LinkedIn
    "platform_content": {
        "instagram": {
            "content": "Instagram version with #hashtags",
            "contentType": "Reels",
            "settings": {"altText": "Image description"}
        },
        "x": {
            "content": "Short version for X (280 chars)"
        },
        "linkedin": {
            "content": "Professional version for LinkedIn"
        }
    }
}).json()

Framework Examples​

OpenClaw / Custom Python Agent​

import requests

class PostEverywhereAgent:
    def __init__(self, api_key):
        self.base = "https://app.posteverywhere.ai/api/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
            "User-Agent": "MyAgent/1.0"
        }

    def get_accounts(self):
        r = requests.get(f"{self.base}/accounts", headers=self.headers)
        return r.json()["data"]["accounts"]

    def post(self, content, account_ids, scheduled_at=None):
        body = {"content": content, "account_ids": account_ids}
        if scheduled_at:
            body["scheduled_at"] = scheduled_at
        r = requests.post(f"{self.base}/posts", headers=self.headers, json=body)
        return r.json()

    def check_results(self, post_id):
        r = requests.get(f"{self.base}/posts/{post_id}/results", headers=self.headers)
        return r.json()["data"]["results"]

# Usage
agent = PostEverywhereAgent("pe_live_...")
accounts = agent.get_accounts()
x_account = next(a for a in accounts if a["platform"] == "x")
result = agent.post("Daily update from my AI agent!", [int(x_account["id"])])

LangChain Tool​

from langchain.tools import tool

@tool
def schedule_social_post(content: str, platforms: str, schedule_time: str = None) -> str:
    """Schedule a social media post to specified platforms.
    
    Args:
        content: The post text content
        platforms: Comma-separated platform names (instagram, x, linkedin, etc.)
        schedule_time: Optional ISO 8601 datetime to schedule for. Omit for immediate.
    """
    import requests
    
    headers = {
        "Authorization": f"Bearer {os.environ['POSTEVERYWHERE_API_KEY']}",
        "Content-Type": "application/json"
    }
    
    # Get accounts matching requested platforms
    accounts = requests.get(
        "https://app.posteverywhere.ai/api/v1/accounts",
        headers=headers
    ).json()["data"]["accounts"]
    
    target_platforms = [p.strip() for p in platforms.split(",")]
    account_ids = [int(a["id"]) for a in accounts if a["platform"] in target_platforms]
    
    if not account_ids:
        return f"No connected accounts for: {platforms}"
    
    body = {"content": content, "account_ids": account_ids}
    if schedule_time:
        body["scheduled_at"] = schedule_time
    
    result = requests.post(
        "https://app.posteverywhere.ai/api/v1/posts",
        headers=headers,
        json=body
    ).json()
    
    if result.get("error"):
        return f"Error: {result['error']['message']}"
    
    return f"Post created: {result['data']['post_id']} (status: {result['data']['status']})"

Error Handling for Agents​

def safe_post(content, account_ids, max_retries=3):
    for attempt in range(max_retries):
        r = requests.post(f"{BASE}/posts", headers=headers, json={
            "content": content,
            "account_ids": account_ids
        })
        
        if r.status_code == 200:
            return r.json()
        elif r.status_code == 429:
            wait = int(r.headers.get("Retry-After", 60))
            time.sleep(wait)
        elif r.status_code >= 500:
            time.sleep(2 ** attempt)
        else:
            return r.json()  # Client error, don't retry
    
    raise Exception("Max retries exceeded")

Daily Posting Agent Pattern​

import schedule
import time

agent = PostEverywhereAgent("pe_live_...")

def daily_post():
    content = generate_content()  # Your AI content generation
    accounts = agent.get_accounts()
    account_ids = [int(a["id"]) for a in accounts]
    result = agent.post(content, account_ids)
    print(f"Posted: {result['data']['post_id']}")

schedule.every().day.at("10:00").do(daily_post)

while True:
    schedule.run_pending()
    time.sleep(60)