---
title: "Discover Agent"
method: POST
path: "/api/v1/registry/discover"
tags: ["registry"]
---

# Discover Agent

`POST /api/v1/registry/discover`

## Request

- Base URL: `https://api.badgeia.com`
- URL: `https://api.badgeia.com/api/v1/registry/discover`
- Auth: none declared

Fetch and validate an agent manifest from a URL.

Tries: {url}/.well-known/agent.json first, then {url}/agent.json as fallback.
Also pings the health endpoint if declared in the manifest.

Requires authentication — registry mutation/discovery is a logged-in-only
action (SEC-AUTH per Phase-1 audit). Without auth, an unauth caller could
cycle the discovery loop to consume server CPU + outbound bandwidth.

## Request body

- ManifestDiscoverRequest: Request to discover an agent from a URL.
  - `url` string, required: Base URL of the agent (manifest fetched from {url}/.well-known/agent.json)

## Response `200`

Successful Response

- ManifestDiscoverResponse: Response from manifest discovery — the parsed manifest + health status.
  - `manifest` AgentManifest, required: The full agent manifest served at /.well-known/agent.json — ARP v2
    - `schema_version` string
    - `name` string, required
    - `description` string, nullable
    - `version` string, nullable
    - `provider` ManifestProvider
      - `name` string, required
      - `url` string, nullable
    - `endpoint` ManifestEndpoint
      - `base_url` string, required
      - `execute` string
      - `health` string
      - `protocol` string
    - `capabilities` ManifestCapabilities
      - `domains` string[]
      - `modalities` string[]
      - `max_context_tokens` integer, nullable
      - `supports_streaming` boolean
      - `supports_tools` boolean
      - `tools` CapabilityTool[], nullable: List of tools/functions the agent can invoke
        - `name` string, required
        - `description` string, nullable
        - `type` string
      - `skills` string[], nullable: High-level skills (e.g. 'code_review', 'data_analysis')
      - `languages` string[], nullable: Programming languages supported
      - `constraints` CapabilityConstraints: Operational constraints for the agent.
        - `max_concurrent_requests` integer, nullable
        - `max_tokens_per_request` integer, nullable
        - `requires_auth` boolean
        - `rate_limit_rpm` integer, nullable: Requests per minute limit
    - `model` ManifestModel
      - `name` string, required
      - `provider` string, required
      - `architecture` string, nullable
    - `auth` ManifestAuth: Authentication requirements for calling the agent.
      - `type` string
      - `header` string
      - `docs_url` string, nullable
    - `evaluation` ManifestEvaluation: Agent's evaluation preferences.
      - `preferred_tasks` string[], nullable: Task domains the agent is optimized for
      - `warm_up_runs` integer: Recommended warm-up runs before scoring
      - `timeout_seconds` integer
    - `schemas` object, nullable: JSON Schema definitions for input/output contracts
    - `benchmarks` object, nullable: Self-reported benchmark scores (e.g. {humaneval: 0.82})
    - `meta` ManifestMeta
      - `tags` string[]
      - `license` string, nullable
      - `source_url` string, nullable
      - `created_at` string, nullable
    - `ml_bom` ManifestMLBom: ARP v2 ML bill-of-materials — models/tools the agent DECLARES it runs. Purely self-reported at this stage (BPP-1 ``declared`` level); later BPP waves (OTel-traced spans, metering, reconciliation) corroborate or contradict these claims — see ``app.services.provenance``. Additive and optional so a legacy manifest with no ``ml_bom`` keeps validating byte-identically.
      - `models` MLBomModel[]
        - `id` string, required
        - `provider` string, nullable
        - `role` string
      - `tools` MLBomTool[]
        - `name` string, required
        - `kind` string, nullable
      - `routing_policy` string, nullable
    - `provenance_public_key` string, nullable: JWK JSON string (Ed25519 OKP only in W1)
    - `signatures` ManifestSignature[], nullable
      - `alg` string, required
      - `jws` string, required: Detached compact JWS: 'header..signature', or full compact 'header.payload.signature' where payload must match the independently-canonicalized manifest bytes.
  - `health_ok` boolean
  - `health_latency_ms` integer, nullable
  - `source_url` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/badgeia/apis/badge.md) · [All operations](https://skmtc.dev/badgeia/apis/badge/llms.txt) · [OpenAPI document](https://skmtc.dev/badgeia/apis/badge/revisions/7e7f7fee8b77?raw)