overads
Browse the docs
Overview

Guides

Scheduling and approvals

How scheduledAt is interpreted, what pending means, and how a post gets through approval.

Scheduling

  • scheduledAt is ISO 8601 with a timezone. Send UTC (Z) to avoid surprises.
  • Omit it and the post is a draft. Set it later with PATCH /posts/:id to schedule.
  • Up to five minutes in the past is moved to now with a SCHEDULED_TIME_COERCED warning, so a script that computed the time before a slow upload does not fail. Earlier than that is refused with SCHEDULED_TIME_IN_PAST.
  • POST /posts/:id/publish skips the queue and delivers now, waiting for the outcome.
  • GET /best-times suggests slots from the workspace's own history.

The approval rule

A scheduled post can be routed through review. Two things route it:

  • The workspace setting requirePostApproval. When it is on, every scheduled post created over the API lands as pending. Owners and admins turn it on in Settings > Rules > Require approval. It holds posts made in the app, by the assistant and by workflows too, and the composer shows its approval switch on and locked while it is on.
  • requireApproval: true on the post itself, the same checkbox the composer shows. Use it when one post needs a second pair of eyes.

Either way the create call succeeds. The post has approvalStatus: "pending", and when the workspace rule caused it the response carries the warning:

{
  "data": { "id": "…", "status": "scheduled", "approvalStatus": "pending" },
  "warnings": [
    { "code": "APPROVAL_REQUIRED", "message": "This workspace requires approval for scheduled posts. The post is queued as pending and will not publish until a member approves it in the app." }
  ]
}

What pending means

  • The post is scheduled and visible in the app's approval queue, but the scheduler will not deliver it until it is approved.
  • POST /posts/:id/publish on a pending post is refused with 409 and code APPROVAL_REQUIRED. There is no API call that approves a post; a member does it in the app.
  • Editing a pending post is allowed. Scheduling a draft through PATCH applies the workspace rule the same way create does.
  • post.approval_required fires when the post enters the queue and post.approved when a reviewer approves it, with approvedBy. Subscribe to both to know when to expect delivery.

Over MCP the same warning rides on create_post and update_post. The server's instructions tell the model to say so and not retry; if you build your own agent, do the same.