Discovery

Discovery is the read-only catalog behind every other plane: agents, skills, plugins, MCP servers, connectors, models, providers and (once you have saved some) workflows. Four routes, all ozk_-authenticated, all backed by the registry service (orchestration/api-gateway/routes/discovery.ts → orchestration/registry/).

8.1 Search — GET /v1/discovery/search

Response: { "cards": [...], "count": <cards in this page>, "total": <every match>, "searchMethod": "text" | "hybrid" | "vector", "query": { …the normalised query… } }. count is the page size; total is every card the filters (and, for q, the keyword predicate) match, ignoring limit and offset — page with offset until you have seen total. For a q search the vector leg can add cards the keyword predicate did not match, so total is a floor, never smaller than offset + count.

curl -s "https://api.plungeai.com/v1/discovery/search?q=web+search&kind=agents&limit=3" \
  -H "Authorization: Bearer $PLUNGE_API_KEY"

curl -s "https://api.plungeai.com/v1/discovery/search?q=llm&kind=agents&limit=2&include=quality" \
  -H "Authorization: Bearer $PLUNGE_API_KEY"

Catalog sizes on 2026-09-18 (limit=100, first page): agents 92, skills 12, plugins 5, providers 11, mcp-servers 100+, models 100+, connectors 802 as of 2026-09-29 (9 pages of 100 — read total), workflows 0 for a fresh key (saved workflows are per user), experts / backgrounds / personas 0 (capability cards are created by users and missions — see Skills, plugins & capability injection).

8.2 The card object

Summary cards (fields=summary, the default for the agents/tools lists) carry: id, type, name, version, description, category, best_for[], not_for[], tags[], status, icon, color, created_at, updated_at. Full cards add parameters[], demonstrations[], prompt_format, output_type, output. Connector cards add a connector object (auth, provider_key, key_placeholder, help_text); model cards add pricing and capability columns from the rate card.

Tags encode the operational facts the planes act on:

8.3 Recommend — POST /v1/discovery/recommend

Body { "type": "agent" | "skill" | … (plural kinds accepted as aliases), "task": "<what you want done>", "status"?: "<status>" }. Since 2026-09-25 recommend rides on the Jev resolve (§8.4) and works again — from 2026-09-18 it answered 502 upstream_error for every request. status defaults to active. Response: { "recommended": "<card id>" | null, "card": { …the card… } | null, "score": <0–1>, "resolve": { …the full resolve decision… } } — recommended is null and score is 0 when nothing fits; score is also 0 on the keyword fallback (no confidence). Only the types in the discovery index can be recommended — agent, skill, connector, mcp_server, workflow, plugin, expert, digital_twin; any other valid type (model, provider, background, component, theme, …) answers 400 type_not_discoverable (legacy aliases such as ai_agent are normalised first), an unknown type 400 invalid_request.

8.4 Resolve — POST /v1/discovery/resolve

One step from a task to a call: which tool, which operation, what command, and how sure the platform is. The registry shortlists cards per kind (BM25 over id, name, description, best_for and tags), one decision request to the Jev model (typesafe-provider) picks a card per kind or none, and the answer carries that card's operation, its required parameters, an example CNL task and a calibrated confidence (orchestration/registry/resolve.ts).

curl -s -X POST "https://api.plungeai.com/v1/discovery/resolve" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "current weather conditions for Berlin", "kinds": ["agents"]}'

The body is whitelisted — any other field is dropped; you never pass an owner or a debug flag, so only public cards are considered.

Response fields:

What each outcome means for a caller:

• match (confidence ≥ 0.8) — call tool.id with operation.name; fill call.required_params (the card at §8.5 has every parameter). Ask your user first when operation.gated is true.
• uncertain — the best guess is below 0.8, or method is lexical-fallback or rate-limited and the pick is a keyword match (confidence: null). Treat tool and the first alternatives as a shortlist: read their cards and choose, or ask your user.
• none — no card in the catalog fits this task, or the task needs no tool at all (plain text answers it). Do not invent an id; answer without a tool or tell your user nothing fits.

Decisions for the same task, kinds, status and category are cached (10 minutes in memory, 6 hours in KV) until the catalog snapshot changes.

8.5 One card — GET /v1/discovery/cards/:type/:id

Returns the full card as markdown with YAML frontmatter (Content-Type: text/markdown) — the same document the platform's own agents read before calling a tool. :type is the singular storage type (agent, skill, plugin, mcp_server, connector, model, provider, workflow, expert, background, digital_twin); the plural kind spellings (agents, mcp-servers, …) are accepted as aliases.

curl -s "https://api.plungeai.com/v1/discovery/cards/agent/brave-agent" \
  -H "Authorization: Bearer $PLUNGE_API_KEY"

Unknown card → 404 not_found. A 4xx from the registry is normalised into the One API error envelope; a registry 5xx never reaches you raw (502 upstream_error).

8.6 From an id to a call

Search results are cached briefly on the platform side (KV + LRU, ~200 ms per uncached call); agents that discover at run time — concierge, the harness loop — hit this same route, so what you see is what they see.