Agent-Ready Directory

The ARD surface: search payable and agent-ready capabilities, explore the catalog, and verify attestations. The registry is self-describing - GET /api/ard returns a service descriptor linking the full catalog dump and the JWKS that verifies attestation signatures.

POST/api/ard/search

Search agentic resources (Agentic Resource Discovery)

Runs an Agentic Resource Discovery (ARD) search over ora's catalog of agent-ready resources. Returns resources ranked by relevance to a free-text query, with optional field filters and federation control. The per-result `score` is pure relevance (0-100): match quality for the query, never a trust or readiness rating. Results are ordered by relevance with agent-readiness reordering close matches, so `score` need not decrease down the list; the readiness itself is in `oraScorecard` and GET /api/score/{domain}. Rate limited to 30 requests per minute per IP - returns 429 if exceeded.

REQUEST BODYrequired

query

object

required

federation

string

Federation policy. 'none': ora's own index only. 'referrals': ora's results plus referrals[] pointers to upstream registries. 'auto': ora merges upstream registry results into results (each tagged with its upstream source); merging is off by default (server-gated), and while it is off 'auto' returns referrals[] as 'referrals' does.auto | referrals | none

pageSize

integer

Results per page (1-100, default 10).

pageToken

string

Opaque pagination token from a previous response. A token ora did not issue returns 400 INVALID_ARGUMENT.

RESPONSES

200The ARD SearchResponse: { results, referrals, pageToken? }. pageToken is omitted when the result set is exhausted (never null). referrals lists upstream registries in 'referrals' mode, and in 'auto' mode while upstream merging is off. Each result's trustManifest.attestations[0] is a reference { type, uri, mediaType } to GET /api/ard/attestation/{domain}, not inlined claims. Results from ora's own index also carry an `oraScorecard` vendor extension ({ score?, grade?, category?, checkedAt? }): agent-readiness score/grade only when ora has scored the domain (never a fabricated 0/F), category whenever ora has classified it - all distinct from the relevance `score`; the signed claim remains the attestation endpoint. Ora product entries (type application/vnd.ora.product+json) reference the JSON score document GET /api/score/{domain} as their url when scored, or carry inline data { domain, name, category?, status: 'not_scanned' } when not, with the human report page in `oraReportUrl`; skill entries use application/agent-skills+md (a type filter on the earlier application/ai-skill+md matches too). Entries crawled from other publishers' catalogs carry `oraPublisherBinding`: 'verified' when the entry's urn:air publisher is the site ora crawled it from, else 'unverified' (ARD §4.5.1); an unverified entry carries no trustManifest and sorts after verified ones at equal relevance.

400INVALID_ARGUMENT - malformed query body. -> ArdErrorResponse

429RATE_LIMIT_EXCEEDED - max 30 requests per minute per IP. -> ArdErrorResponse

500INTERNAL_ERROR -> ArdErrorResponse

POST/api/ard/explore

Faceted exploration of agentic resources (Agentic Resource Discovery)

Returns facet aggregations (counts per field value) for an Agentic Resource Discovery (ARD) result set. Use this to build filter UIs over the ARD catalog. A `type` bucket's value is the raw media type, so it can be used as a filter value as-is. An optional query narrows the set before faceting: with text, the set is exactly what POST /api/ard/search matches for the same text and filter; without it, the whole index narrowed by the filter. Rate limited to 30 requests per minute per IP - returns 429 if exceeded.

REQUEST BODYrequired

query

object

Optional query to narrow the set before faceting (same shape as POST /api/ard/search's query).

resultType

object

required

RESPONSES

200Facet aggregations for the matched resource set.

400INVALID_ARGUMENT - malformed query body. -> ArdErrorResponse

429RATE_LIMIT_EXCEEDED - max 30 requests per minute per IP. -> ArdErrorResponse

500INTERNAL_ERROR -> ArdErrorResponse

GET/api/ard/attestation/{domain}

Get a signed scorecard attestation for a domain (Agentic Resource Discovery)

Returns an Agentic Resource Discovery (ARD) scorecard attestation for the given domain. When ora has an attestation signing key configured, the payload is returned as an EdDSA detached JWS that verifies against the public JWK set at GET /api/ard/jwks (also served at /.well-known/jwks.json); without a configured key the attestation is returned unsigned. Rate limited to 60 requests per minute per IP - returns 429 if exceeded.

PARAMETERS

domain

string

path

required

The domain to attest (e.g. stripe.com).

RESPONSES

200The scorecard attestation - an EdDSA detached JWS when signing is configured, otherwise an unsigned payload.

400INVALID_ARGUMENT - malformed domain. -> ArdErrorResponse

404NOT_FOUND - no cached score for this domain. Body also carries `next` pointing at POST /api/scan. -> ArdErrorResponse

429RATE_LIMIT_EXCEEDED - max 60 requests per minute per IP. -> ArdErrorResponse

500INTERNAL_ERROR -> ArdErrorResponse