Agents: checks that run on a schedule, people approve

An agent is a background job that runs on a schedule in your workspace, looks at your posts and writes proposals: hold this post, fix this caption. An agent never changes a post on its own. Nothing changes until a person approves the proposal.

Manage agents in the app under Tools → Agents at https://postboost.co/app/{workspaceUuid}/agents (admins and members), through the API (tag Agents) or from an AI assistant with the MCP connector.

The pre-publish checker

There are two agent types: the pre-publish checker (pre_publish_checker) and the failed-post fixer (failed_post_fixer). Each time the pre-publish checker runs, it looks at the posts scheduled for the next horizon_hours (default 24, up to 168): at most 200 posts and 25 links per run.

It proposes holding a post (hold_post: move it back to draft) when:

Finding	Severity
An account needs reconnecting (see connection health)	critical
The X monthly allowance is used up, once it is enforced (not yet, see X policy)	critical
The post fails a network's requirements for the post	critical
The account's daily post limit is reached (see guardrails)	warning
A link in the post is dead (HTTP 400 or higher, or unreachable)	warning

One post gets one hold proposal that lists every reason.

It proposes a caption edit (edit_caption: replace the text of one caption) when:

• the caption contains one of your banned_phrases. The proposal removes the phrase (severity warning);
• ai_review is on and the AI suggests a better caption, written in your workspace brand voice (severity info). Each reviewed post uses 1 AI text credit. max_ai_reviews_per_run caps how many posts one run reviews, and the review stops when credits run out.

The same pending proposal is never created twice.

Settings

Setting	Default	Allowed
horizon_hours	24	1 to 168
check_links	true	turn the dead-link check off with false
banned_phrases	[]	up to 50 phrases, 2 to 100 characters each
ai_review	false	needs AI features in your plan
max_ai_reviews_per_run	10	1 to 50

Schedule

schedule is hourly (default), every_6_hours, daily or weekly. A new agent runs within about 5 minutes, then on its schedule. A paused agent (enabled: false) does not run. Run now in the app (or runAgent in the API) starts a run right away: up to 6 times an hour, and not while a run is already going. A workspace has one agent of each type.

The failed-post fixer

The failed-post fixer (failed_post_fixer) looks at the posts that failed on one or more accounts in the last lookback_hours (default 24, 1 to 72; at most 200 posts per run). For each failed account on a post it proposes one next step:

Finding	Proposal	Severity
The account must be reconnected (see connection health)	reconnect_account, with a link to the accounts page	critical
The text is over the network's limit (PostBoost's own check before publishing, or the network's error says so)	retry_account with the caption cut to the network's limit at a word boundary, ending in "…", counted the way the network counts (X counts links as 23 and CJK characters as two)	warning
Anything else (rate limit, timeout, server error)	retry_account with the caption unchanged	warning

Each proposal shows the error (up to 300 characters). It uses no AI and no credits, and it never retries on its own. A failure gets one proposal: rejecting it means the agent does not propose it again until the account fails again.

Approving retry_account saves the shortened caption (if any) on that account's own version, so the other accounts keep the original text, then publishes that account again. If the account is no longer failed, the post is publishing right now, or your plan does not allow scheduling, the proposal becomes stale and nothing is published. Approving reconnect_account only records your decision: reconnect the account, then the next run proposes the retry. Open failed-post proposals expire once the account is no longer failed on the post. Each failed account has at most one open proposal: a newer one (after you edit the post or reconnect the account) replaces the older one, which becomes expired.

The approval queue

Proposals wait in the Approval queue tab. Each one shows its severity, the reason, the accounts, the scheduled time and a link to the post. A caption edit also shows the text before and after. Add a note if you like (up to 1000 characters), then:

• Approve: the change is applied at once. A hold moves the post back to draft; a caption edit replaces the text; a retry publishes the failed account again.
• Reject: nothing changes. PostBoost records who decided, when and your note.

For holds and caption edits: if the post changed after the proposal was made (it was edited, deleted or is no longer scheduled), approving applies nothing and marks the proposal stale. Failed-post proposals follow their own rules. Your edits are never overwritten. A pending proposal whose post was deleted, unscheduled or whose time has passed becomes expired. All statuses: pending, applied, rejected, stale, failed, expired.

The Run history tab lists the last 20 runs with their trigger, status, duration, posts checked, proposals created and a summary.

Daily digest email

Once a day at 08:00 UTC, workspace admins get one email listing what is waiting for a decision: pending agent proposals (critical first, up to 20 items) and inbox reply drafts that have waited more than 4 hours. No email is sent when nothing is waiting.

API

Operation	Method and path
listAgents	GET /{workspaceUuid}/agents
createAgent	POST /{workspaceUuid}/agents
updateAgent	PUT /{workspaceUuid}/agents/{agentUuid}
deleteAgent	DELETE /{workspaceUuid}/agents/{agentUuid}
runAgent	POST /{workspaceUuid}/agents/{agentUuid}/run (202; 409 while a run is going)
listAgentRuns	GET /{workspaceUuid}/agents/{agentUuid}/runs
getAgentRun	GET /{workspaceUuid}/agent-runs/{runUuid}
listAgentProposals	GET /{workspaceUuid}/agent-proposals (status, default pending)
approveAgentProposal	POST /{workspaceUuid}/agent-proposals/{proposalUuid}/approve
rejectAgentProposal	POST /{workspaceUuid}/agent-proposals/{proposalUuid}/reject

Everyone in the workspace can read agents, runs and proposals. Creating, changing and deciding needs an admin or member. Approving answers with the proposal and its new status (applied, stale or failed), or 409 if it was already decided.

curl -X POST "https://postboost.co/app/api/$WORKSPACE_UUID/agents" \
  -H "Authorization: Bearer $POSTBOOST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pre_publish_checker",
    "schedule": "every_6_hours",
    "settings": { "horizon_hours": 48, "banned_phrases": ["limited time only"] }
  }'

From an AI assistant

The MCP connector has list-agents, list-agent-proposals, approve-agent-proposal and reject-agent-proposal. A good assistant shows you the proposals and approves or rejects only the ones you agree with.