Approvals

Workspaces can require human review before a post is published. This is useful when an AI agent or junior team member drafts content but a manager signs off. Postato tracks the review state and integrates with the dashboard.

How a post enters approval

A workspace enables approvals via its policy. When the policy matches (e.g., "all posts by agents require approval"), a POST /posts call with status: "publish" does NOT deliver immediately. Instead:

1. The post is created with status: "pending_approval".
2. A record is created in the approval queue.
3. Reviewers with the posts.approve permission see it in the dashboard's Approvals page, or via the REST GET /approvals endpoint.
4. The approval.requested webhook fires.

Reviewer actions

From the dashboard (or REST):

• Approve: the post transitions to queued and delivery proceeds normally.
• Reject: the post is terminated. Reviewer can attach a comment explaining why.
• Request changes: reviewer leaves a comment; the original author (or an agent operating on their behalf) updates and resubmits.

The approval.decided webhook fires on any terminal outcome with { decision, reviewerId, comment }.

Polling from an agent

If your agent submitted a post and wants to wait for the decision:

publish_post → { postId, status: "pending_approval" }
  ↓ poll every few seconds (or wait for webhook)
get_approval_status(postId) → { status: "pending" }
  ↓ user approves in dashboard
get_approval_status(postId) → { status: "approved", reviewerId, decidedAt }

Prefer webhooks for production. Polling is fine for interactive sessions where the agent wants to surface the outcome back to the user within a single conversation.

Permission model

Two permissions govern approval workflows:

• posts.publish: can create posts that may enter approval.
• posts.approve: can decide on pending approvals.

An agent typically has posts.publish and NOT posts.approve. A human reviewer has the reverse. A workspace admin has both.

Scheduling and approvals

Scheduled posts can also require approval. In that case:

1. Post created with status: "pending_approval", scheduledAt: "...".
2. Reviewer approves or rejects.
3. If approved BEFORE scheduledAt, the post transitions to scheduled and fires normally.
4. If approved AFTER scheduledAt, the post transitions to queued immediately (and fires right away).
5. Rejection is terminal regardless of timing.

Bypass

Callers with posts.publish_without_approval (reserved for trusted integrations) skip the approval queue entirely. Don't grant this to AI agents unless you've audited their behavior.

Audit trail

Every decision is logged with reviewer identity, timestamp, and comment. Visible in the dashboard's audit log and via GET /audit/workspace REST endpoint.