Review Agent Changes

You choose whether a change from an agent key goes live at once or waits for an editor. Turn on Review agent changes in Admin > Settings > API, and a change from an agent key to anything that readers can see waits in Admin > Proposals until an editor approves it.

Every organization that you create starts with the review on. An organization from before the review keeps direct agent changes until an admin turns it on.

What waits for review

• A change to a published page: its text, title, section label, status, or visibility.
• A publish request: a status that publishes a draft. The proposal holds the title and the text, so you approve the text that goes live.
• A move of a published page to another section.
• A change to the landing page.
• A published changelog entry: a new one, a change, or a delete.
• The API reference: a sync of an OpenAPI spec that adds, changes, or removes pages, a detach of the spec, and a move of a published API reference page. The proposal holds the spec, so you approve the spec that goes live.
• A change to the workspace settings. Only an admin can approve it.
• A scheduled import run that changes or removes a published page. See Scheduled imports below.

These changes still save at once, because readers don't see them: drafts, new draft pages, new sections, and image uploads. Edits that your team makes in the app aren't affected. While the review is on, an agent key can't delete a workspace or create a public or listed one. Ask an admin to do it, or approve the key as a publishing key.

What the agent gets

The agent gets a review link instead of a live change, and it gives you the link. When the same key sends the same change again, ContextOwl updates its proposal, so a CI job that pushes a change twice files one proposal. When the key sends a change that matches the live page, ContextOwl withdraws its proposal, and the queue shows it as withdrawn by the agent.

Approve changes

Open Admin > Proposals. Each row says what the change does, for example Publish getting-started: DRAFT to STABLE. A chip says where the change came from: via MCP, via API, or via import. Admins also see the name of the agent key.

1. Select View to see the text diff and the fields that change.
2. Select Approve to apply the change, or Reject to close it.

An approved publish request publishes the page, and it puts the page in the sidebar when the page has no section. When the page changed after the agent made the proposal, ContextOwl asks before it replaces the newer change. When the agent changed the proposal after you opened it, ContextOwl asks you to check it again.

Publishing keys

An admin can approve an agent key once as a publishing key. Its changes then go live at once, also while the review is on. Approve only keys that you control, such as the key of your GitHub Action:

1. Open Admin > Settings > API.
2. Select Approve publishing on the row of the key, or select Publish directly when you create the key.

The Review agent changes card lists the publishing keys, and Remove ends an approval. The audit log records each approval and each removal.

Scheduled imports

A scheduled run of an import connection follows the review too. It sends a change to a published page, and the removal of a published page, to Admin > Proposals. Published pages keep their place and their sidebar label until an editor approves. Drafts still update at once, and drafts that the source dropped are deleted. A run that you start with Import now applies at once.

A later run updates the same proposal of each page. When the source has the text of the page again, the run withdraws the proposal, and the queue shows it as withdrawn by the import. An approved removal archives the page. When the connection removes the pages that the source drops, its next run deletes the archived page.

An admin can let a connection publish its scheduled runs at once:

1. Open Admin > Import.
2. Select Approve publishing on the connection, or turn on Publish scheduled runs directly when you connect a source.

A change of the source settings or the credential removes the approval. The audit log records each approval and each removal.

A scheduled run sends no proposal.created webhook event for its proposals, because one run can change hundreds of pages. Its run report and its content.imported row in the audit log give the number of proposals that it filed.

Turn the review off

Turn off Review agent changes to let agent keys change live content at once. Proposals that are open stay open, and an editor can still approve them.

Get notified

Subscribe a webhook to proposal.created to tell your editors that a change waits, and to proposal.approved to follow the approvals. Open Admin > Settings > API > Webhooks.