How agents use VoxBurst

A conceptual guide for AI agents (and the humans who prompt them) explaining the correct mental model for orchestrating VoxBurst tools.

The five-step mental model

A competent agent should always follow this sequence:

1. IDENTIFY  →  find the right account ID(s)
2. VALIDATE  →  check content against platform rules (optional but recommended)
3. CREATE    →  create the post with the right parameters
4. INSPECT   →  check the result after publishing
5. RECOVER   →  retry or fix if any platform failed

Never skip to CREATE without knowing the account ID. Never skip INSPECT after publishing. Always be ready to RECOVER.

Step 1 — Identify accounts

Always start here. VoxBurst targets specific connected accounts, not platform names.

list_accounts()

Look for accounts where connected: true and match on platform and username. Store the id — that’s what goes in accountIds.

If the user says “post to my Instagram account” and there are two Instagram accounts connected, ask the user which one before proceeding.

Step 2 — Validate (optional but recommended)

Before creating a post with a long caption, emoji-heavy text, or multi-platform targets, validate first:

validate_content(
  content: "your caption",
  platforms: ["INSTAGRAM", "TWITTER"]
)

When to always validate:

• Caption is close to a character limit
• Targeting platforms with strict rules (Bluesky’s 300-grapheme limit, Instagram’s media requirement)
• First time posting to a platform in this session

When you can skip validation:

• Short caption, well-known platform, no unusual characters
• Already validated the same content moments ago

Step 3 — Create with the right parameters

create_post(
  content: "...",
  accountIds: ["acc_..."],
  contentType: "IMAGE",  ← required for Instagram
  mediaUrls: [...],      ← required for Instagram
  scheduledFor: "...",   ← omit to post immediately
  firstComment: "...",   ← optional
)

Key rules:

• accountIds is always an array, even for a single account
• contentType is required for Instagram — never omit it
• mediaUrls must be public HTTPS URLs — no local paths
• mediaIds for pre-uploaded VoxBurst files
• scheduledFor is ISO 8601 UTC — 2026-06-01T15:00:00Z

Step 4 — Inspect the result

Always check what happened:

get_post(postId: "post_abc123")

What to look for:

Read platforms[].platformPostUrl to get the live URL for each successful platform.

Step 5 — Recover if needed

If any platform failed:

retry_post(postId: "post_abc123")

This re-queues only the failed platforms. Successful ones are never re-posted.

If a platform has retryCount: 3 (exhausted automatic retries):

• Use the REST /v1/posts/:id/platforms/:platformId/fix endpoint
• Pass a corrected mediaUrl or content if the failure was content/media related

See the Recovery playbook for the full decision tree.

Understanding post status

draft ──────────→ scheduled ──→ publishing ──→ published
  ↑                                  ↓              ↓
  └── (cancel/unschedule)         failed        partial
                                     ↓              ↓
                                  retry          retry
                                     ↓              ↓
                                 published      published

Valid tool actions from each status:

What agents should tell users

On success:

“Your [post type] is [scheduled for / live on] [platform(s)]. [URLs if published]”

On partial failure:

“Your post published on [successful platforms], but [failed platform] failed: [reason]. I retried it — [new status].”

On full failure:

“The post failed on all platforms. The error was: [reason]. [What I did to fix it / what you should do next].”

On needing clarification:

“I found [N] connected [platform] accounts: [list with usernames]. Which one should I use?”

Common agent mistakes to avoid