How to require sign-off on AI-written documents

Comments tell an agent what to fix. An approval tells everyone the document is ready: a named person looked at a specific revision and signed off. This guide shows how to require that sign-off on documents your AI agent writes, and how the agent can check the result before it acts.

Written in October 2026. Approvals are opt-in per document, and turning them on is a Pro feature.

When to use approvals

Most documents never need them. A research note or a status update is fine with comments alone. Use approvals when something depends on the document being final:

• A plan the agent will execute once a person agrees.
• A report that goes to leadership or a customer.
• A decision record, RFC, or postmortem that a named person must accept.

How approvals work

• Opt-in per document. Nothing changes for a document until an owner or editor requests review on it. Documents that never request review show no approval controls at all.
• Bound to a revision. An approval applies to the exact revision the reviewer looked at. When the agent publishes a new revision, the document goes back in review, so an old sign-off can't cover text nobody has read.
• Four states: draft, in review, approved, and changes requested.
• Who can decide. Owners, editors, and commenters can approve or request changes. Reviewers don't need a paid plan. When requesting changes, the reviewer includes a note saying what should change.
• Plans. The owner needs Pro to turn approvals on. If a plan later lapses, the current state and history are kept, but a new review cycle can't start.

1. Request review

Ask your agent to start the review once the draft is ready:

Publish the migration plan, then request review on it.

The agent publishes with publish_document, then calls request_review. The first call turns approvals on for that document; later calls start a new review cycle. Reviewers you've added as collaborators can then approve or request changes on the page.

2. Reviewers decide

A reviewer reads the revision, optionally adds inline comments on specific passages, and then either approves or requests changes. Comments and the decision are separate: comments point at passages, the decision is about the whole revision.

If the agent revises after a "changes requested" decision, the new revision goes back in review and the reviewer decides again. Using Show changes next to the revision number, they can check only what changed.

3. The agent checks the outcome

Before the agent acts on a document, have it read the state:

Check the review state of the migration plan. Only continue if it's approved on the current revision.

get_review_state returns the state, the revision it applies to, the document's current head revision, and recent decisions with each reviewer's note. On a document without approvals it returns enabled: false rather than an error.

Compare the approved revision with the head revision. If they differ, the approval is out of date.

4. Revising after "changes requested"

Read the review state and the open comments on the migration plan. Address what the reviewer asked for, publish a new revision, and resolve the comments you've handled.

The agent uses get_review_state for the reviewer's note, list_comments or get_feedback for the inline feedback, and update_document, reply_to_comment, and resolve_comment to finish the round. See how your agent finds out about new comments for polling and webhooks.

Rules for agents

• Never approve on someone's behalf. The approve tool is a sign-off, and it should only be used when the person the agent acts for has actually reviewed the revision.
• Don't skip the check. If an action depends on approval, read get_review_state first, every time.
• Don't request review by default. Only when the user wants a sign-off.

Getting notified

On Pro, webhooks send a signed request to your own endpoint when review is requested (document.review_requested) and when a document is approved (document.approved). There is no webhook for "changes requested" yet, so have the agent read get_review_state to see that decision.

Questions

Do reviewers need an account? To approve, yes, since a sign-off has to belong to someone. They don't need a paid plan.

Can I use approvals on a private document? Yes. Reviewers just need to be invited as collaborators.

Where does the record live? In the document's history, next to every revision and who wrote it. See document provenance explained.

More on running the whole loop: human-in-the-loop review for AI-written documents, or see the For agents page.