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 a readiness-weighted relevance score (0-100): match quality for the query (dominant), multiplied by a 0.6-1.0 factor from the domain's agent-readiness. It is distinct from the raw agent-readiness score returned by POST /api/scan 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 degrades to own-results-only when disabled.auto | referrals | none

pageSize

integer

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

pageToken

string

Opaque pagination token from a previous response.

RESPONSES

200The ARD SearchResponse: { results, referrals, pageToken? }. pageToken is omitted when the result set is exhausted (never null). ora is non-federating, so referrals is []. 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.

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. An optional query narrows the set before faceting. 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