---
title: "Refresh agent snapshot"
method: POST
path: "/api/registry/agents/{encodedUrl}/refresh"
tags: ["Agent Compliance"]
---

# Refresh agent snapshot

`POST /api/registry/agents/{encodedUrl}/refresh`

Re-probe the agent and update its registry health (online, tools_count, response_time_ms), capability snapshot (inferred type, discovered tools), and compliance verdict (storyboard pass/fail counts). Use after fixing your agent so the registry shows fresh data without waiting for the periodic heartbeat (~1h).

**Compliance re-run:** when the caller owns the agent or is an AAO admin and the capability probe succeeds, the full storyboard suite can run for several minutes on capability-rich agents with a fresh test session, and `agent_storyboard_status` is updated. Owner-triggered runs use `triggered_by: 'owner_test'`; admin-triggered support runs use `triggered_by: 'manual'`. Badge fan-out reissues verification badges off the new run. If the compliance call fails (timeout, OAuth wall, internal error), the capability/health portion still returns successfully — `compliance.ran` is `false` with an `error` string.

**Auth:** owner of the agent, AAO admin, or static `ADMIN_API_KEY`.

**Rate limits:** 60 seconds per agent URL, 30 requests per user per hour.

## Path parameters

- `encodedUrl` string, required — URL-encoded agent URL

## Response `200`

Snapshot refreshed

- object
  - `online` boolean, required
  - `tools_count` integer, nullable, required
  - `response_time_ms` integer, nullable, required
  - `inferred_type` string, required — Type inferred from discovered tools (sales, creative, signals, governance, etc.) or 'unknown'
  - `type_promoted` boolean, required — True when registry type was upgraded from unknown to inferred_type
  - `oauth_required` boolean, required
  - `checked_at` string, required
  - `error` string
  - `compliance` object, required — Compliance re-run summary. The capability/health portion of the response is independent of this block — a failed compliance run still returns the rest of the snapshot.
    - `ran` boolean, required — True if the full storyboard suite ran and agent_storyboard_status was updated. False when ownership couldn't be resolved, the agent reported auth_required, or the compliance call itself failed.
    - `run_id` string — Compliance run id written by this refresh. Use with /compliance/diagnostics?run_id=... to inspect failing-step wire evidence.
    - `test_session_id` string — Fresh test session id used for the compliance run. Useful when matching seller-side logs to the refresh.
    - `requested_compliance_target` string — Requested compliance target before alias resolution, e.g. 3.1, 3.0, 3.1-rc, or 3.1-beta. Present when `ran` is true.
    - `adcp_version` string — Concrete AdCP compliance bundle version used for the run, e.g. 3.0.12 or 3.1.0-beta.7. Present when `ran` is true.
    - `badge_eligible` boolean — True when this run can update public badge state.
    - `badge_eligible_adcp_versions` string[] — Public badge versions this run can issue, e.g. ['3.0'].
    - `overall_status` string — Aggregate verdict from the run (passing / failing / partial / unknown). Only present when `ran` is true.
    - `storyboards_passing` integer — Number of storyboards passing on this run.
    - `storyboards_total` integer — Number of storyboards evaluated on this run.
    - `observations_count` integer — Number of advisory observations emitted by this run.
    - `notices_count` integer — Number of run-summary notices emitted by this run.
    - `error` string — Reason compliance didn't run when `ran` is false.

## Other responses

- `400` — Invalid agent URL
- `401` — Authentication required
- `403` — Not authorized — must be owner or AAO admin
- `409` — Monitoring paused for this agent
- `429` — Rate limit exceeded
- `502` — Probe failed (timeout, DNS, OAuth wall, etc.)

---

[API](https://skmtc.net/adcontextprotocol/apis/agenticadvertising-org-registry-api.md) · [All operations](https://skmtc.net/adcontextprotocol/apis/agenticadvertising-org-registry-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/adcontextprotocol/agenticadvertising-org-registry-api/versions/9ea7fedf54c0/schema)