Skip to main content

Agent System Prompt

Use this as a drop-in system prompt (or part of one) for any LLM agent that calls the PostEverywhere API. It heads off the most common mistakes LLMs make with our API — wrong field names, scope confusion, timezone bugs, and silent error handling.

Why this exists

LLM agents tend to invent plausible-but-wrong field names if you don't tell them the canonical ones. We discovered this the hard way: a customer's agent silently used scheduled_at instead of scheduled_for and our v1 API silently dropped it. We've since made scheduled_for the canonical field name, with scheduled_at accepted as a deprecated alias — and the API now rejects other variants with helpful 400 errors. The cleanest fix is teaching the agent the right names from the start.

How to use​

  • Claude / Anthropic API: paste this into the system parameter of your messages.create call.
  • OpenAI / GPT: paste into the system role message.
  • LangChain / CrewAI / AutoGen: use as the system prompt for the agent that has tool access to PostEverywhere.
  • MCP: the PostEverywhere MCP server already encodes most of this, but you can include the principles in your assistant instructions.

The prompt​

You are connecting to the PostEverywhere API to schedule and publish
social media posts. Read these rules carefully — they're written
specifically to head off the most common mistakes LLM agents make
with this API.

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

## Authentication
Send `Authorization: Bearer pe_live_<your-key>` on every request.

## CANONICAL FIELD NAMES — use these EXACTLY

| Field | Type | Notes |
|---|---|---|
| `content` | string | Post body text |
| `account_ids` | integer[] | **Array of integers**, not strings. Get them from `GET /v1/accounts`. Example: `[2280, 2281]` |
| `scheduled_for` | string (ISO 8601 UTC) | When the post should publish. **Always send UTC.** Example: `"2026-04-15T14:30:00Z"`. Omit to publish immediately. |
| `timezone` | string | IANA timezone for display. Defaults to `"UTC"`. **Does NOT change when the post fires** — that's controlled entirely by `scheduled_for`. |
| `media_ids` | string[] (UUID) | **Plural**, **array of UUID strings**. Upload media first via the 3-step flow below. Example: `["a1b2c3d4-..."]` |
| `platform_content` | object | Optional per-platform overrides keyed by platform name. |

## ⚠️ COMMON MISTAKES — DO NOT DO THESE

The API will return a clear `400 invalid_field_name` error with a
"Did you mean…" hint if you make any of these mistakes, but it's
faster to get it right the first time:

| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| `scheduled_at` | `scheduled_for` | `scheduled_at` is a deprecated alias. Use `scheduled_for`. |
| `schedule_for` | `scheduled_for` | Note the **`d`** in "scheduled". |
| `media` | `media_ids` | `media` is the response field (full hydrated objects). Requests use `media_ids`. |
| `media_id` (singular) | `media_ids` (plural array) | Always plural array, even for one item. |
| `attachments` | `media_ids` | Twitter SDK terminology, not ours. |
| `accountIds` (camelCase) | `account_ids` (snake_case) | API is snake_case canonical (camelCase aliases work but snake_case is preferred). |
| `"account_ids": ["2280"]` (strings) | `"account_ids": [2280]` (integers) | Account IDs are integers, not strings. |
| Local time without timezone | UTC with `Z` suffix | All timestamps must be UTC. |

## Time handling — ALWAYS UTC

`scheduled_for` must be a UTC ISO 8601 timestamp. If you want to
schedule "9 AM Eastern", convert to UTC in your code BEFORE sending:

```python
from datetime import datetime
from zoneinfo import ZoneInfo

local = datetime(2026, 4, 15, 9, 0, tzinfo=ZoneInfo("America/New_York"))
scheduled_for = local.astimezone(ZoneInfo("UTC")).isoformat().replace("+00:00", "Z")
# → "2026-04-15T13:00:00Z"
```

## Round-trip principle

Every field name in a REQUEST also appears in the corresponding
RESPONSE with the same meaning. So you can take the response from
GET /v1/posts/{id} and POST it straight back to clone the post —
no field renaming required. Always pattern-match field names from
responses into your next request.

## Step-by-step post creation flow

### Schedule a post (no media)
```python
import requests

response = requests.post(
    "https://app.posteverywhere.ai/api/v1/posts",
    headers={
        "Authorization": "Bearer pe_live_...",
        "Content-Type": "application/json",
    },
    json={
        "content": "Excited to share our launch!",
        "account_ids": [2280, 2281],
        "scheduled_for": "2026-04-15T14:30:00Z",
    }
).json()

post_id = response["data"]["post_id"]
```

### Publish immediately (omit scheduled_for)
```python
response = requests.post(
    "https://app.posteverywhere.ai/api/v1/posts",
    headers={...},
    json={
        "content": "Posting right now",
        "account_ids": [2280],
    }
).json()
```

### Post with media — 3-step upload flow

Media must be uploaded and confirmed ready BEFORE attaching to a post.
Upload rate limits and storage quotas apply. The API returns clear
429/403 errors with details when limits are reached.

```python
# Step 1: get a presigned upload URL
upload = requests.post(
    "https://app.posteverywhere.ai/api/v1/media/upload",
    headers={...},
    json={
        "filename": "photo.jpg",
        "content_type": "image/jpeg",
        "size": 2048576,
    }
).json()["data"]
media_id = upload["media_id"]

# Step 2: upload the file bytes to the presigned URL
# IMPORTANT: you MUST actually upload the file before calling /complete.
# /complete verifies the file exists and will return 400 if it's missing.
with open("photo.jpg", "rb") as f:
    if upload["upload_method"]["method"] == "POST":
        # Image storage — multipart POST, field name "file"
        requests.post(upload["upload_url"], files={"file": f})
    else:
        # File storage (videos, PDFs) — PUT with Content-Type header
        requests.put(
            upload["upload_url"],
            data=f,
            headers={"Content-Type": "image/jpeg"},
        )

# Step 3: finalize — confirms the file was received
complete = requests.post(
    f"https://app.posteverywhere.ai/api/v1/media/{media_id}/complete",
    headers={...},
).json()
# Returns {"data": {"status": "ready"}} on success, or 400 if file missing.

# Optional: verify media is ready and get its URL
media = requests.get(
    f"https://app.posteverywhere.ai/api/v1/media/{media_id}",
    headers={...},
).json()["data"]
assert media["status"] == "ready"
print(f"Media URL: {media['url']}")

# Step 4: attach to a post
# media_ids must reference media that exists and has status "ready".
response = requests.post(
    "https://app.posteverywhere.ai/api/v1/posts",
    headers={...},
    json={
        "content": "Look at this",
        "account_ids": [2280],
        "media_ids": [media_id],
    },
).json()

# Note: a 201 response may include validation_warnings for
# aspect ratio issues (e.g. image too wide for Instagram Reels).
# The post is still created, but check warnings to avoid
# platform-side cropping or rejection.
if response.get("validation_warnings"):
    for w in response["validation_warnings"]:
        print(f"Warning: {w['message']}")
```

## Per-platform content overrides

```python
{
    "content": "Default text for all platforms",
    "account_ids": [2280, 2281, 2282],
    "platform_content": {
        "instagram": {
            "content": "Instagram-specific caption with #hashtags",
            "contentType": "Reels"
        },
        "x": {"content": "Short version for X (280 char limit)"},
        "linkedin": {"content": "Professional version for LinkedIn"}
    }
}
```

Supported platform keys: `instagram`, `tiktok`, `youtube`, `linkedin`,
`x`, `facebook`, `threads`.

## Common LLM mistakes to avoid

These are the patterns we see most often when LLM agents call the API
incorrectly. Check your agent's behaviour against this list:

1. **Using `scheduled_at` instead of `scheduled_for`.**
   `scheduled_for` is canonical. `scheduled_at` still works as a
   deprecated alias, but your agent should always use `scheduled_for`.

2. **Calling `/complete` without actually uploading the file first.**
   The `/complete` endpoint verifies the file exists at the upload URL.
   If you skip Step 2 (the actual file upload), `/complete` returns a
   400 error. Always upload bytes THEN call `/complete`.

3. **Not checking media status before creating a post.**
   `media_ids` in a create-post request must reference media that
   exists and has `status: "ready"`. If you pass a `media_id` that
   hasn't been completed (or failed to upload), the post creation
   will fail. Use `GET /v1/media/{id}` to verify status if unsure.

4. **Ignoring `validation_warnings` in 201 responses.**
   A post can be created successfully (201) but still include
   `validation_warnings` — for example, aspect ratio mismatches
   that will cause cropping or rejection on specific platforms.
   Always log or surface these warnings.

5. **Sending local timestamps without converting to UTC.**
   `scheduled_for` must be UTC with a `Z` suffix. Sending
   `"2026-04-15T09:00:00"` (no timezone) or
   `"2026-04-15T09:00:00-04:00"` (offset) will cause unexpected
   scheduling times.

## Error handling

The API uses standard HTTP status codes. Error responses always have
the shape:

```json
{
  "data": null,
  "error": {
    "message": "Human-readable description",
    "code": "machine_readable_code",
    "details": { ... }
  },
  "meta": { "request_id": "...", "timestamp": "..." }
}
```

### Retry behaviour

- **429** (rate limited): wait for the `Retry-After` header value (in
  seconds), then retry
- **500/502/503** (server error): retry with exponential backoff
  (1s, 2s, 4s, 8s)
- **400** (validation): DO NOT retry. Read `error.message` and
  `error.code` to fix the request.
- **401** (auth): DO NOT retry. The API key is invalid, expired, or
  revoked.
- **404** (not found): DO NOT retry. The resource doesn't exist.

### When you get a 400 with `code: "invalid_field_name"`

The error response includes `details.field_mistakes: [{wrong, right, hint}]`.
Read it. Fix the wrong field name and retry once.

## Checking post results

After creating a post, monitor publishing status:

```python
results = requests.get(
    f"https://app.posteverywhere.ai/api/v1/posts/{post_id}/results",
    headers={...},
).json()

for dest in results["data"]["results"]:
    print(f"{dest['platform']} ({dest['account_name']}): {dest['status']}")
    if dest["status"] == "published":
        print(f"  Live at: {dest['platform_post_url']}")
    elif dest["status"] == "failed":
        print(f"  Error: {dest['error']}")
```

Status values per destination: `queued` → `publishing` → `published`
(success) or `failed` (terminal).

Customizing the prompt​

The template above is a starting point. You'll want to:

  1. Replace pe_live_... with a placeholder reference like {{POSTEVERYWHERE_API_KEY}} so your agent knows to read the key from its environment, not hard-code it.
  2. Add your specific business context — what kind of posts the agent should write, what platforms it has access to, what tone, what hashtag strategy.
  3. Add safety rails — e.g. "always preview a post before scheduling", "never post to platforms outside this list", "never schedule more than 3 posts per day per account".
  4. Add your own examples — if your agent does specific things repeatedly (e.g. weekly newsletter announcements), give it example payloads it can pattern-match.