API Reference

Supported public contracts for the browser SDK, A2W runs, Connect AI MCP/REST, and product analytics calls.

Use the contract that matches the caller. A website installs the browser SDK, an outside agent starts an A2W run, and an owner's AI uses a site-scoped Connect AI key. Rover's Firebase control plane and /v2/rover/* session routes are first-party implementation details, not integration APIs.

Caller	Public contract	Start here
Your website	Generated embed tag and browser SDK methods	Configuration
An AI visiting the site	A2W runs at `https://agent.rtrvr.ai/v2/a2w`	The A2W section below
Your own AI editing Rover	Connect AI over MCP or `roverConfigApi/v1`	The Connect AI section below
Your product analytics code	`trackGoal`, `trackEvent`, and `trackConversion`	Rover Analytics

Public authentication

Browser install uses the public pk_site_* value generated in Workspace. It is exchanged for Rover-managed session auth; do not put server secrets or session tokens in page code.
A2W create may be anonymous. The response mints the access token used to poll, stream, continue, or cancel that run.
Signed A2W callers may use RFC 9421 HTTP Message Signatures with Signature, Signature-Input, and Signature-Agent for verified attribution.
Delegated A2W work uses a scoped rds_* token created by the human verification flow, never a site key.
Connect AI uses the bearer key shown once when an owner creates or rotates a site-scoped connection.

Agent-to-Web Protocol (A2W) API (`/v2/a2w/runs`)

Neutral AI / CLI protocol for Rover-enabled sites. POST is the structured API-agent path. GET /v2/a2w/runs is the compact URL-fetch chatbot path and can extract one canonical browser selector from the target URL. The source-visible marker <script type="application/agent+json"> stays compact and points agents to the live well-known files and OpenAPI.

POST `/v2/a2w/runs`

Create a strict v2 A2W run for any Rover-enabled site using a target URL and exactly one launch selector.

Auth: Anonymous public access token minted in response. Initial create call requires no site public key.

Required request fields
Field	Type	Description
`url`	`string`	Target page URL on a Rover-enabled site.

Optional request fields
Field	Type	Description
`prompt`	`string`	Canonical natural-language instruction for the run.
`shortcutId`	`string`	Exact saved shortcut/capability ID. Use for repeatable flows.
`playbookId`	`string`	Exact experience playbook ID. Use when the owner has published a guided outcome path.
`engagementKind`	`'demo' \| 'onboarding' \| 'support' \| 'task'`	Optional explicit kind. It must agree with a selected shortcut or playbook.
`capabilityId`	`string`	Explicit page/site capability identifier when the caller already knows the target skill.
`args`	`Record<string, unknown>`	Structured run arguments for the selected capability.
`identity`	`{ userPresent?, sessionId?, agentKey?, memoryKey? }`	Typed caller and session attribution.
`execution`	`{ preference?: 'cloud' \| 'browser' \| 'auto'; mode?: 'cloud' \| 'browser'; allowedModes?: ('cloud' \| 'browser')[]; userPresent?: boolean }`	Structured execution preference for POST callers.
`accept`	`{ modes?, primary? }`	Requested text, markdown, json, observation, or artifacts result modes.
`policy`	`{ confirmation?, crossHost?, maxHops? }`	Execution policy that the site may narrow.
`agent`	`{ key?, displayName?, vendor?, model?, version?, homepage?, memoryKey?, clientId? }`	Typed visiting-agent attribution.
`subject` / `auth` / `payment` / `commerce`	typed objects	Sensitive or structured scoping accepted only on POST, never in browser or GET links.
`confirmationPolicy` / `artifacts`	typed fields	Charge-confirmation policy and requested artifact names.

Success example

{
  "id": "a2w_run_123",
  "protocol": "a2w",
  "runId": "a2w_run_123",
  "run": "https://agent.rtrvr.ai/v2/a2w/runs/a2w_run_123?access=a2w_access_...",
  "workflow": "https://agent.rtrvr.ai/v2/a2w/workflows/a2w_wf_456?access=a2w_access_...",
  "status": "running",
  "retryAfterMs": 2000,
  "links": {
    "poll": { "href": "https://agent.rtrvr.ai/v2/a2w/runs/a2w_run_123?access=a2w_access_...", "method": "GET", "headers": { "Accept": "application/json", "Prefer": "wait=10" } },
    "stream": { "href": "https://agent.rtrvr.ai/v2/a2w/runs/a2w_run_123?access=a2w_access_...", "method": "GET", "headers": { "Accept": "text/event-stream" } },
    "ndjson": { "href": "https://agent.rtrvr.ai/v2/a2w/runs/a2w_run_123?access=a2w_access_...", "method": "GET", "headers": { "Accept": "application/x-ndjson" } }
  },
  "open": "https://rtrvr.ai/#rover_receipt=a2w_receipt_...",
  "browserLink": "https://rtrvr.ai/?rover=get+me+the+latest+blog+post#rover_receipt=a2w_receipt_..."
}

Notes:

Headers drive advanced behavior: Accept, Prefer: wait=15, Prefer: execution=cloud|browser|auto, and Idempotency-Key.
Exactly one of prompt, shortcutId, or playbookId is required. Unknown properties and conflicting kinds fail with typed contract errors.
If no explicit agent object is provided, Rover can still attribute the caller heuristically from User-Agent, Signature-Agent, Signature, Signature-Input, and X-RTRVR-Client-Id.
Default execution mode is cloud for URL-fetch agents. open is the clean receipt-based browser handoff, while browserLink is an optional readable alias when the visible deep link stays within a conservative URL budget.
Use Prefer: execution=cloud, wait=10 for cloud-hosted execution with a short initial wait, then follow links.stream, links.ndjson, or links.poll until terminal or input_required.

GET `/v2/a2w/runs?url=<target>&prompt=<task>`

Create a hosted-cloud A2W run for URL-fetch chatbots that cannot POST.

Auth: Anonymous public access token minted in response. Target site must have AI access and cloud browser execution enabled.

Required request fields
Field	Type	Description
`url`	`string`	Absolute HTTPS target page URL on a Rover-enabled site.

Optional request fields
Field	Type	Description
`prompt`	`string`	Natural-language task. Use exactly one selector.
`shortcutId`	`string`	Exact saved shortcut ID. Use exactly one selector.
`playbookId`	`string`	Exact saved playbook ID. Use exactly one selector.
`engagementKind`	`'demo' \| 'onboarding' \| 'support' \| 'task'`	Optional explicit kind; stored kinds remain authoritative.
`execution`	`'cloud' \| 'browser'`	Defaults to cloud.
`wait`	`number`	Initial long-poll wait in seconds. Defaults to 25 and caps server-side.
`format`	`'markdown' \| 'json'`	Defaults to markdown unless JSON is requested.

Success example

# Rover A2W run

Status: running
Run: https://agent.rtrvr.ai/v2/a2w/runs/a2w_run_123?access=a2w_access_...

## Still running

Rover is running this task in a hosted cloud browser. Fetch the poll URL until terminal or input_required.

## Links

- Poll: https://agent.rtrvr.ai/v2/a2w/runs/a2w_run_123?access=a2w_access_...&format=markdown&wait=10

Notes:

This is the no-browser path for ChatGPT, Claude, Gemini, and similar URL-fetch agents.
Long-running markdown responses include a self-contained poll URL with format=markdown&wait=10.
GET executor responses send X-Robots-Tag: noindex, nofollow, noarchive.

GET `/v2/a2w/runs/{id}`

Read the canonical public A2W run resource as JSON, markdown, SSE, or NDJSON.

Auth: Run access token via ?access= or Authorization: Bearer ....

Notes:

Accept: application/json returns latest state or final result.
format=markdown returns chatbot-readable markdown.
Accept: text/event-stream streams uniform run events.
Accept: application/x-ndjson streams the same events in CLI-friendly NDJSON.

POST `/v2/a2w/runs/{id}`

Continue a run that is waiting on user input.

Auth: Run access token.

Required request fields
Field	Type	Description
`input`	`string`	Ordinary continuation answer. Required unless `answers` is sent.

Optional request fields
Field	Type	Description
`answers`	`Record<string, string>`	Per-question answers keyed by `input.questions[].key` — use this when the park asked multiple questions. A bare `input` string binds the same text to every key; unknown keys are ignored.

Notes:

Only for ordinary input_required questions. Reasons carrying input.links.confirm or input.links.verify (payment_confirmation_required, auth_required, action_confirmation_required, ...) complete out-of-band — relay the link to the human and poll; do not POST input to those runs.
Sign-in walls (input.reason=sign_in_link_required) resume via POST /v2/a2w/runs/{id}/auth-input instead.

POST `/v2/a2w/runs/{id}/auth-input`

Provide the sign-in magic link or one-time code a human received, so a run parked with input.reason=sign_in_link_required can resume.

Auth: Run access token.

Required request fields
Field	Type	Description
`value`	`string`	The sign-in link or one-time code.

Optional request fields
Field	Type	Description
`kind`	`'magic_link' \| 'otp' \| 'unknown'`	Required type of the one-shot value.

Notes:

The value is a secret: stored encrypted, consumed one-shot to resume the run, and never returned in any payload, event, or model context.
run.authInput describes what is expected (status, kind, prompt, emailMasked) and never carries the provided value.
Returns the updated run resource; resume is driven asynchronously — keep polling links.self.

DELETE `/v2/a2w/runs/{id}`

Cancel an in-flight A2W run.

Auth: Run access token.

GET `/v2/a2w/runs/{id}/artifacts`

Mint short-lived signed download URLs for the files a run generated (screenshots, PDFs, sheets).

Auth: Run access token.

Notes:

The run result lists generated files as opaque storage refs; this endpoint turns them into fetchable URLs on read.
Signed URLs expire after ~15 minutes — re-GET to refresh. Runs that produced files advertise this endpoint as links.artifacts.
Response shape: { runId, expiresAt, artifacts: [{ name, contentType, sizeBytes, url, expiresAt }] }.

GET `/v2/a2w/capabilities?url=<site>`

List a Rover-enabled site's published capabilities as MCP-shaped tools.

Auth: Anonymous. RFC 9421 Web Bot Auth signing raises the trust tier.

Required request fields
Field	Type	Description
`url`	`string`	Target site URL. Required unless `host` or `siteId` is passed.

Optional request fields
Field	Type	Description
`host`	`string`	Site host, as an alternative to `url`.
`siteId`	`string`	Explicit Rover site identifier.

Notes:

Returns { protocol: 'mcp', serverInfo, executor: { contract: 'a2w', runEndpoint }, mcp: { transport: 'streamable-http', url }, tools }.
Every tool executes Rover-mediated through the canonical A2W run contract; MCP-native agents can instead connect to the returned live MCP server URL.

POST `/v2/a2w/runs/{id}/handoffs`

Create a delegated child run on another Rover-enabled site and keep the same workflow lineage.

Auth: Parent run access token.

Required request fields
Field	Type	Description
`url`	`string`	Target Rover-enabled site URL.

Optional request fields
Field	Type	Description
`prompt`	`string`	Delegation request. Use exactly one selector.
`shortcutId`	`string`	Exact shortcut to run on the receiving site.
`playbookId`	`string`	Exact playbook to run on the receiving site.
`engagementKind`	`'demo' \| 'onboarding' \| 'support' \| 'task'`	Optional explicit kind; it must agree with stored configuration.
`capabilityId`	`string`	Explicit child-run capability identifier.
`args`	`Record<string, unknown>`	Structured arguments for the delegated capability.
`identity`	`{ userPresent?, sessionId?, agentKey?, memoryKey? }`	Typed child-run identity hints.
`execution`	`{ preference?, mode?, allowedModes?, userPresent? }`	Cloud/browser execution policy for the child run.
`accept`	`{ modes?: ('text' \| 'markdown' \| 'json' \| 'observation' \| 'artifacts')[] }`	Requested child-run result modes.
`policy`	`{ confirmation?: 'auto' \| 'required' \| 'site_policy'; crossHost?: 'allow' \| 'same_host' \| 'site_policy' }`	Execution-policy hints for the child run.
`agent`	`{ key?, displayName?, vendor?, model?, version?, homepage?, memoryKey?, clientId? }`	Optional child-run agent identity override. If omitted, parent attribution is inherited.
`contextSummary`	`string`	Structured summary to carry into the child run.
`expectedOutput`	`string`	Describe what the child should return to the parent workflow.
`lastObservation`	`Record<string, unknown>`	Latest structured parent observation when needed for delegation.

Notes:

Delegated child runs are still ordinary A2W run resources; they simply inherit the parent's workflow lineage.
Receiving sites must enable siteConfig.aiAccess.allowDelegatedHandoffs in Workspace.

GET `/v2/a2w/workflows/{id}`

Read the aggregated cross-site workflow resource as JSON, SSE, or NDJSON.

Auth: Workflow access token via ?access= or Authorization: Bearer ....

Notes:

Accept: application/json returns the latest workflow snapshot and final result when available.
Accept: text/event-stream or Accept: application/x-ndjson streams workflow-level lineage across parent and child runs.

Connect AI: MCP and REST

Create a connection under Workspace Connect AI. Its bearer key is bound to one site, supports redacted reads and proposals only, and is shown once. A site may have up to eight active connections.

Surface	Endpoint
MCP over HTTP	`https://us-central1-rtrvr-extension-functions.cloudfunctions.net/roverConfigMcp`
REST base	`https://us-central1-rtrvr-extension-functions.cloudfunctions.net/roverConfigApi/v1`
Auth header	`Authorization: Bearer <YOUR-KEY>`

REST routes
Method and path	Result
`GET /sites`	Sites visible to the key. A site-scoped connection resolves only its bound site.
`GET /sites/{siteId}/config?fields=a,b`	Current redacted configuration, optionally projected to top-level fields.
`GET /sites/{siteId}/journeys`	Journey summaries.
`GET /sites/{siteId}/journeys/{journeyId}`	One full journey definition.
`GET /sites/{siteId}/analytics/summary?range=7d\|30d`	Aggregate counts only; no visitor-level data.
`GET /sites/{siteId}/changes`	One page of pending proposals.
`GET /sites/{siteId}/briefs/{section}`	A redacted brief for `journeys`, `knowledge`, `appearance`, or `audience`.
`POST /sites/{siteId}/changes`	Create a pending proposal. The owner must keep it in Workspace.
`POST /validate`	Validate and normalize a patch without writing a change.

Create a proposal

{
  "patch": {
    "productKnowledge": [
      { "id": "pricing", "title": "Pricing", "body": "...", "kind": "pricing" }
    ]
  },
  "title": "Clarify the pricing facts",
  "description": "Uses the current public pricing copy.",
  "clientRequestId": "pricing-docs-2026-08-12"
}

A proposal returns changeId, status: 'pending', reviewUrl, and droppedPaths. Unknown or unsupported fields are reported rather than applied. clientRequestId must be stable across retries.

MCP tools
Tool	Purpose
`list_sites`	List the bound owner's sites visible to this connection.
`get_config_section`	Read current redacted configuration, optionally by top-level field.
`list_journeys` / `get_journey`	Read journey summaries or one complete journey.
`get_analytics_summary`	Read a 7- or 30-day aggregate summary.
`list_pending_changes`	List proposals waiting for owner review.
`get_config_brief`	Read a section-specific brief before drafting a patch.
`validate_config_patch`	Dry-run a patch through the same sanitizer used for proposals.
`propose_config_change`	Create a pending, reviewable configuration change.
`draft_journey`	Draft one preview journey as a pending proposal.

No direct apply endpoint

Connect AI can read, validate, and propose. It cannot publish. The owner applies or discards every proposal in Workspace.

ConfigurationThe production tag, supported SDK options, identity, and runtime methods.Connect Your AICreate, rotate, and revoke a site-scoped configuration connection.A2W guideDiscovery, run creation, streaming, continuation, and handoffs.

API Reference

Supported public contracts for the browser SDK, A2W runs, Connect AI MCP/REST, and product analytics calls.

Caller	Public contract	Start here
Your website	Generated embed tag and browser SDK methods	Configuration
An AI visiting the site	A2W runs at `https://agent.rtrvr.ai/v2/a2w`	The A2W section below
Your own AI editing Rover	Connect AI over MCP or `roverConfigApi/v1`	The Connect AI section below
Your product analytics code	`trackGoal`, `trackEvent`, and `trackConversion`	Rover Analytics

Public authentication

Browser install uses the public pk_site_* value generated in Workspace. It is exchanged for Rover-managed session auth; do not put server secrets or session tokens in page code.
A2W create may be anonymous. The response mints the access token used to poll, stream, continue, or cancel that run.
Signed A2W callers may use RFC 9421 HTTP Message Signatures with Signature, Signature-Input, and Signature-Agent for verified attribution.
Delegated A2W work uses a scoped rds_* token created by the human verification flow, never a site key.
Connect AI uses the bearer key shown once when an owner creates or rotates a site-scoped connection.

Agent-to-Web Protocol (A2W) API (`/v2/a2w/runs`)

POST `/v2/a2w/runs`

Create a strict v2 A2W run for any Rover-enabled site using a target URL and exactly one launch selector.

Auth: Anonymous public access token minted in response. Initial create call requires no site public key.

Required request fields
Field	Type	Description
`url`	`string`	Target page URL on a Rover-enabled site.

Optional request fields
Field	Type	Description
`prompt`	`string`	Canonical natural-language instruction for the run.
`shortcutId`	`string`	Exact saved shortcut/capability ID. Use for repeatable flows.
`playbookId`	`string`	Exact experience playbook ID. Use when the owner has published a guided outcome path.
`engagementKind`	`'demo' \| 'onboarding' \| 'support' \| 'task'`	Optional explicit kind. It must agree with a selected shortcut or playbook.
`capabilityId`	`string`	Explicit page/site capability identifier when the caller already knows the target skill.
`args`	`Record<string, unknown>`	Structured run arguments for the selected capability.
`identity`	`{ userPresent?, sessionId?, agentKey?, memoryKey? }`	Typed caller and session attribution.
`execution`	`{ preference?: 'cloud' \| 'browser' \| 'auto'; mode?: 'cloud' \| 'browser'; allowedModes?: ('cloud' \| 'browser')[]; userPresent?: boolean }`	Structured execution preference for POST callers.
`accept`	`{ modes?, primary? }`	Requested text, markdown, json, observation, or artifacts result modes.
`policy`	`{ confirmation?, crossHost?, maxHops? }`	Execution policy that the site may narrow.
`agent`	`{ key?, displayName?, vendor?, model?, version?, homepage?, memoryKey?, clientId? }`	Typed visiting-agent attribution.
`subject` / `auth` / `payment` / `commerce`	typed objects	Sensitive or structured scoping accepted only on POST, never in browser or GET links.
`confirmationPolicy` / `artifacts`	typed fields	Charge-confirmation policy and requested artifact names.

Success example

{
  "id": "a2w_run_123",
  "protocol": "a2w",
  "runId": "a2w_run_123",
  "run": "https://agent.rtrvr.ai/v2/a2w/runs/a2w_run_123?access=a2w_access_...",
  "workflow": "https://agent.rtrvr.ai/v2/a2w/workflows/a2w_wf_456?access=a2w_access_...",
  "status": "running",
  "retryAfterMs": 2000,
  "links": {
    "poll": { "href": "https://agent.rtrvr.ai/v2/a2w/runs/a2w_run_123?access=a2w_access_...", "method": "GET", "headers": { "Accept": "application/json", "Prefer": "wait=10" } },
    "stream": { "href": "https://agent.rtrvr.ai/v2/a2w/runs/a2w_run_123?access=a2w_access_...", "method": "GET", "headers": { "Accept": "text/event-stream" } },
    "ndjson": { "href": "https://agent.rtrvr.ai/v2/a2w/runs/a2w_run_123?access=a2w_access_...", "method": "GET", "headers": { "Accept": "application/x-ndjson" } }
  },
  "open": "https://rtrvr.ai/#rover_receipt=a2w_receipt_...",
  "browserLink": "https://rtrvr.ai/?rover=get+me+the+latest+blog+post#rover_receipt=a2w_receipt_..."
}

Notes:

Headers drive advanced behavior: Accept, Prefer: wait=15, Prefer: execution=cloud|browser|auto, and Idempotency-Key.
Exactly one of prompt, shortcutId, or playbookId is required. Unknown properties and conflicting kinds fail with typed contract errors.
If no explicit agent object is provided, Rover can still attribute the caller heuristically from User-Agent, Signature-Agent, Signature, Signature-Input, and X-RTRVR-Client-Id.
Default execution mode is cloud for URL-fetch agents. open is the clean receipt-based browser handoff, while browserLink is an optional readable alias when the visible deep link stays within a conservative URL budget.
Use Prefer: execution=cloud, wait=10 for cloud-hosted execution with a short initial wait, then follow links.stream, links.ndjson, or links.poll until terminal or input_required.

GET `/v2/a2w/runs?url=<target>&prompt=<task>`

Create a hosted-cloud A2W run for URL-fetch chatbots that cannot POST.

Auth: Anonymous public access token minted in response. Target site must have AI access and cloud browser execution enabled.

Required request fields
Field	Type	Description
`url`	`string`	Absolute HTTPS target page URL on a Rover-enabled site.

Optional request fields
Field	Type	Description
`prompt`	`string`	Natural-language task. Use exactly one selector.
`shortcutId`	`string`	Exact saved shortcut ID. Use exactly one selector.
`playbookId`	`string`	Exact saved playbook ID. Use exactly one selector.
`engagementKind`	`'demo' \| 'onboarding' \| 'support' \| 'task'`	Optional explicit kind; stored kinds remain authoritative.
`execution`	`'cloud' \| 'browser'`	Defaults to cloud.
`wait`	`number`	Initial long-poll wait in seconds. Defaults to 25 and caps server-side.
`format`	`'markdown' \| 'json'`	Defaults to markdown unless JSON is requested.

Success example

# Rover A2W run

Status: running
Run: https://agent.rtrvr.ai/v2/a2w/runs/a2w_run_123?access=a2w_access_...

## Still running

Rover is running this task in a hosted cloud browser. Fetch the poll URL until terminal or input_required.

## Links

- Poll: https://agent.rtrvr.ai/v2/a2w/runs/a2w_run_123?access=a2w_access_...&format=markdown&wait=10

Notes:

This is the no-browser path for ChatGPT, Claude, Gemini, and similar URL-fetch agents.
Long-running markdown responses include a self-contained poll URL with format=markdown&wait=10.
GET executor responses send X-Robots-Tag: noindex, nofollow, noarchive.

GET `/v2/a2w/runs/{id}`

Read the canonical public A2W run resource as JSON, markdown, SSE, or NDJSON.

Auth: Run access token via ?access= or Authorization: Bearer ....

Notes:

Accept: application/json returns latest state or final result.
format=markdown returns chatbot-readable markdown.
Accept: text/event-stream streams uniform run events.
Accept: application/x-ndjson streams the same events in CLI-friendly NDJSON.

POST `/v2/a2w/runs/{id}`

Continue a run that is waiting on user input.

Auth: Run access token.

Required request fields
Field	Type	Description
`input`	`string`	Ordinary continuation answer. Required unless `answers` is sent.

Optional request fields
Field	Type	Description
`answers`	`Record<string, string>`	Per-question answers keyed by `input.questions[].key` — use this when the park asked multiple questions. A bare `input` string binds the same text to every key; unknown keys are ignored.

Notes:

Only for ordinary input_required questions. Reasons carrying input.links.confirm or input.links.verify (payment_confirmation_required, auth_required, action_confirmation_required, ...) complete out-of-band — relay the link to the human and poll; do not POST input to those runs.
Sign-in walls (input.reason=sign_in_link_required) resume via POST /v2/a2w/runs/{id}/auth-input instead.

POST `/v2/a2w/runs/{id}/auth-input`

Provide the sign-in magic link or one-time code a human received, so a run parked with input.reason=sign_in_link_required can resume.

Auth: Run access token.

Required request fields
Field	Type	Description
`value`	`string`	The sign-in link or one-time code.

Optional request fields
Field	Type	Description
`kind`	`'magic_link' \| 'otp' \| 'unknown'`	Required type of the one-shot value.

Notes:

The value is a secret: stored encrypted, consumed one-shot to resume the run, and never returned in any payload, event, or model context.
run.authInput describes what is expected (status, kind, prompt, emailMasked) and never carries the provided value.
Returns the updated run resource; resume is driven asynchronously — keep polling links.self.

DELETE `/v2/a2w/runs/{id}`

Cancel an in-flight A2W run.

Auth: Run access token.

GET `/v2/a2w/runs/{id}/artifacts`

Mint short-lived signed download URLs for the files a run generated (screenshots, PDFs, sheets).

Auth: Run access token.

Notes:

The run result lists generated files as opaque storage refs; this endpoint turns them into fetchable URLs on read.
Signed URLs expire after ~15 minutes — re-GET to refresh. Runs that produced files advertise this endpoint as links.artifacts.
Response shape: { runId, expiresAt, artifacts: [{ name, contentType, sizeBytes, url, expiresAt }] }.

GET `/v2/a2w/capabilities?url=<site>`

List a Rover-enabled site's published capabilities as MCP-shaped tools.

Auth: Anonymous. RFC 9421 Web Bot Auth signing raises the trust tier.

Required request fields
Field	Type	Description
`url`	`string`	Target site URL. Required unless `host` or `siteId` is passed.

Optional request fields
Field	Type	Description
`host`	`string`	Site host, as an alternative to `url`.
`siteId`	`string`	Explicit Rover site identifier.

Notes:

Returns { protocol: 'mcp', serverInfo, executor: { contract: 'a2w', runEndpoint }, mcp: { transport: 'streamable-http', url }, tools }.
Every tool executes Rover-mediated through the canonical A2W run contract; MCP-native agents can instead connect to the returned live MCP server URL.

POST `/v2/a2w/runs/{id}/handoffs`

Create a delegated child run on another Rover-enabled site and keep the same workflow lineage.

Auth: Parent run access token.

Required request fields
Field	Type	Description
`url`	`string`	Target Rover-enabled site URL.

Optional request fields
Field	Type	Description
`prompt`	`string`	Delegation request. Use exactly one selector.
`shortcutId`	`string`	Exact shortcut to run on the receiving site.
`playbookId`	`string`	Exact playbook to run on the receiving site.
`engagementKind`	`'demo' \| 'onboarding' \| 'support' \| 'task'`	Optional explicit kind; it must agree with stored configuration.
`capabilityId`	`string`	Explicit child-run capability identifier.
`args`	`Record<string, unknown>`	Structured arguments for the delegated capability.
`identity`	`{ userPresent?, sessionId?, agentKey?, memoryKey? }`	Typed child-run identity hints.
`execution`	`{ preference?, mode?, allowedModes?, userPresent? }`	Cloud/browser execution policy for the child run.
`accept`	`{ modes?: ('text' \| 'markdown' \| 'json' \| 'observation' \| 'artifacts')[] }`	Requested child-run result modes.
`policy`	`{ confirmation?: 'auto' \| 'required' \| 'site_policy'; crossHost?: 'allow' \| 'same_host' \| 'site_policy' }`	Execution-policy hints for the child run.
`agent`	`{ key?, displayName?, vendor?, model?, version?, homepage?, memoryKey?, clientId? }`	Optional child-run agent identity override. If omitted, parent attribution is inherited.
`contextSummary`	`string`	Structured summary to carry into the child run.
`expectedOutput`	`string`	Describe what the child should return to the parent workflow.
`lastObservation`	`Record<string, unknown>`	Latest structured parent observation when needed for delegation.

Notes:

Delegated child runs are still ordinary A2W run resources; they simply inherit the parent's workflow lineage.
Receiving sites must enable siteConfig.aiAccess.allowDelegatedHandoffs in Workspace.

GET `/v2/a2w/workflows/{id}`

Read the aggregated cross-site workflow resource as JSON, SSE, or NDJSON.

Auth: Workflow access token via ?access= or Authorization: Bearer ....

Notes:

Accept: application/json returns the latest workflow snapshot and final result when available.
Accept: text/event-stream or Accept: application/x-ndjson streams workflow-level lineage across parent and child runs.

Connect AI: MCP and REST

Create a connection under Workspace Connect AI. Its bearer key is bound to one site, supports redacted reads and proposals only, and is shown once. A site may have up to eight active connections.

Surface	Endpoint
MCP over HTTP	`https://us-central1-rtrvr-extension-functions.cloudfunctions.net/roverConfigMcp`
REST base	`https://us-central1-rtrvr-extension-functions.cloudfunctions.net/roverConfigApi/v1`
Auth header	`Authorization: Bearer <YOUR-KEY>`

REST routes
Method and path	Result
`GET /sites`	Sites visible to the key. A site-scoped connection resolves only its bound site.
`GET /sites/{siteId}/config?fields=a,b`	Current redacted configuration, optionally projected to top-level fields.
`GET /sites/{siteId}/journeys`	Journey summaries.
`GET /sites/{siteId}/journeys/{journeyId}`	One full journey definition.
`GET /sites/{siteId}/analytics/summary?range=7d\|30d`	Aggregate counts only; no visitor-level data.
`GET /sites/{siteId}/changes`	One page of pending proposals.
`GET /sites/{siteId}/briefs/{section}`	A redacted brief for `journeys`, `knowledge`, `appearance`, or `audience`.
`POST /sites/{siteId}/changes`	Create a pending proposal. The owner must keep it in Workspace.
`POST /validate`	Validate and normalize a patch without writing a change.

Create a proposal

{
  "patch": {
    "productKnowledge": [
      { "id": "pricing", "title": "Pricing", "body": "...", "kind": "pricing" }
    ]
  },
  "title": "Clarify the pricing facts",
  "description": "Uses the current public pricing copy.",
  "clientRequestId": "pricing-docs-2026-08-12"
}

A proposal returns changeId, status: 'pending', reviewUrl, and droppedPaths. Unknown or unsupported fields are reported rather than applied. clientRequestId must be stable across retries.

MCP tools
Tool	Purpose
`list_sites`	List the bound owner's sites visible to this connection.
`get_config_section`	Read current redacted configuration, optionally by top-level field.
`list_journeys` / `get_journey`	Read journey summaries or one complete journey.
`get_analytics_summary`	Read a 7- or 30-day aggregate summary.
`list_pending_changes`	List proposals waiting for owner review.
`get_config_brief`	Read a section-specific brief before drafting a patch.
`validate_config_patch`	Dry-run a patch through the same sanitizer used for proposals.
`propose_config_change`	Create a pending, reviewable configuration change.
`draft_journey`	Draft one preview journey as a pending proposal.

No direct apply endpoint

Connect AI can read, validate, and propose. It cannot publish. The owner applies or discards every proposal in Workspace.

API Reference

Public authentication

Agent-to-Web Protocol (A2W) API (/v2/a2w/runs)

POST /v2/a2w/runs

GET /v2/a2w/runs?url=<target>&prompt=<task>

GET /v2/a2w/runs/{id}

POST /v2/a2w/runs/{id}

POST /v2/a2w/runs/{id}/auth-input

DELETE /v2/a2w/runs/{id}

GET /v2/a2w/runs/{id}/artifacts

GET /v2/a2w/capabilities?url=<site>

POST /v2/a2w/runs/{id}/handoffs

GET /v2/a2w/workflows/{id}

Connect AI: MCP and REST

API Reference

Public authentication

Agent-to-Web Protocol (A2W) API (/v2/a2w/runs)

POST /v2/a2w/runs

GET /v2/a2w/runs?url=<target>&prompt=<task>

GET /v2/a2w/runs/{id}

POST /v2/a2w/runs/{id}

POST /v2/a2w/runs/{id}/auth-input

DELETE /v2/a2w/runs/{id}

GET /v2/a2w/runs/{id}/artifacts

GET /v2/a2w/capabilities?url=<site>

POST /v2/a2w/runs/{id}/handoffs

GET /v2/a2w/workflows/{id}

Connect AI: MCP and REST

Agent-to-Web Protocol (A2W) API (`/v2/a2w/runs`)

POST `/v2/a2w/runs`

GET `/v2/a2w/runs?url=<target>&prompt=<task>`

GET `/v2/a2w/runs/{id}`

POST `/v2/a2w/runs/{id}`

POST `/v2/a2w/runs/{id}/auth-input`

DELETE `/v2/a2w/runs/{id}`

GET `/v2/a2w/runs/{id}/artifacts`

GET `/v2/a2w/capabilities?url=<site>`

POST `/v2/a2w/runs/{id}/handoffs`

GET `/v2/a2w/workflows/{id}`

Agent-to-Web Protocol (A2W) API (`/v2/a2w/runs`)

POST `/v2/a2w/runs`

GET `/v2/a2w/runs?url=<target>&prompt=<task>`

GET `/v2/a2w/runs/{id}`

POST `/v2/a2w/runs/{id}`

POST `/v2/a2w/runs/{id}/auth-input`

DELETE `/v2/a2w/runs/{id}`

GET `/v2/a2w/runs/{id}/artifacts`

GET `/v2/a2w/capabilities?url=<site>`

POST `/v2/a2w/runs/{id}/handoffs`

GET `/v2/a2w/workflows/{id}`