Agent API

Governed Agent Actions

Product

Optimly Actions

Updated

2026-08-09

Optimly Agent Actions let an authorized agent propose and execute bounded work without giving it unrestricted publishing access. Every mutation follows the same auditable lifecycle.

Lifecycle

1. Discover — call /capabilities and verify the resolved organization, brand, permissions, and

advertised endpoints.

1. Propose — create one immutable action with the exact target, payload, evidence, and expected

outcome.

1. Request approval — submit that action for review by the authorized brand approver.
2. Wait — poll or read the action until an explicit approved decision is recorded. A request for

approval is not approval.

1. Execute — call the advertised mutation endpoint with the approved action envelope.
2. Verify — read the resulting state and record whether the intended outcome was achieved.

Never publish, correct brand data, or execute an external mutation while approval is pending, rejected, expired, revoked, or bound to a different payload.

Action endpoints

Discover these operations from /capabilities; the current endpoint families are:

Paths are relative to https://app.optimly.ai/api/v1/agent. The capability response remains authoritative if this list changes.

Mutation envelope

Every mutation supplies the identifiers that bind execution to the approved proposal:

{
  "action_id": "action_...",
  "approval_id": "approval_...",
  "idempotency_key": "stable-key-for-this-exact-operation",
  "actor": {
    "type": "agent",
    "id": "worker-identity"
  }
}

Reuse the same idempotency key only when retrying the same approved operation. Before retrying after a timeout or network failure, read the action and idempotency state. A successful replay should return or reconcile with the original result rather than execute the mutation twice.

On-site action examples

• Update approved page copy, titles, descriptions, headings, structured data, internal links, or FAQs.
• Publish an approved landing page, comparison page, evidence page, or llms.txt update.
• Correct verified Business Profile or BrandVault information used by Optimly and connected agents.
• Implement a website change through the customer's authorized CMS, repository, or deployment path.

Off-site action examples

• Correct an approved third-party listing or directory profile.
• Prepare and send approved outreach to a publisher, partner, analyst, or citation source.
• Submit an approved coverage opportunity or factual correction through an authorized channel.
• Record the verified outcome of external work in the action ledger.

Each connector may impose narrower permissions. The agent must use only the destination, fields, and action types included in the approved proposal.

Analytics and attribution

Capture a baseline before execution and compare the relevant Site Analytics, Agent Analytics, and goal evidence afterward. Keep human sessions, AI referrals, crawler requests, and conversions separate. A crawler request is evidence of agent activity; it is not proof that an AI system caused a human conversion.

Understand Site Analytics and review Agent Analytics evidence.