Nevermined ARD Registry API
The ARD Registry API from Nevermined — 3 operation(s) for ard registry.
The ARD Registry API from Nevermined — 3 operation(s) for ard registry.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/nevermined-app:nevermined-app-ard-registry-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: NVM BACKEND ARD Registry API
description: ''
version: 1.103.0
contact: {}
servers:
- url: https://api.live.nevermined.app
tags:
- name: ARD Registry
paths:
/api/v1/ard/search:
post:
description: 'Relevance-ranked search over listed catalog services. `text` is required; `filter` accepts a bounded supported term set (type, tags, capabilities, publisher, pay:*). Each result carries `identifier`, a closed `matchReason`, per-item `rankingSource`, exactly one scale-specific score, and `source`. `federation` (§5.4) controls cross-registry routing: `none` (local only), `referrals` (also list configured peer registries), or `auto` (fan out and merge, gated). Public. Optional `Authorization: Bearer `: for an account that can use the Nevermined Subscription, each `nvm:catalog.endpoints[]` entry the subscription can pay carries `subscription`: `{ estimatedCreditsPerCall }`, an estimate, since each call is priced from what the merchant quotes for it (`POST /api/v1/router/subscription/quote` gives the exact credits). Send `Nevermined-Version: 1.91` or later: an older version reads it on no endpoint. No `subscription` field means credits are not offered for that endpoint. A missing or refused key is served the anonymous response, never a 401. A keyed read counts against the per-key rate limit of that key and is never shared-cached. Peer results never carry it.'
operationId: ArdRegistryController_search
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ArdSearchRequestDto'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ArdSearchResponseDto'
'400':
description: Missing `text`, or an unsupported filter term (INVALID_ARGUMENT).
'429':
description: Rate limit exceeded.
'503':
description: Credits eligibility could not be read (ARD INTERNAL); retry or search without funding.
summary: ARD registry search (semantic ranking, lexical fallback, federation)
tags:
- ARD Registry
/api/v1/ard/explore:
post:
description: 'Facet aggregation over the matched set (type, publisher, pay:protocol, tags), narrowed by `text`/`filter` using lexical relevance. Returns `{ resultType: "facets", facets }`. Public.'
operationId: ArdRegistryController_explore
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ArdExploreRequestDto'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ArdExploreResponseDto'
'400':
description: Unsupported facet field or filter term (INVALID_ARGUMENT).
'429':
description: Rate limit exceeded.
summary: ARD registry explore (facets)
tags:
- ARD Registry
/api/v1/ard/agents:
get:
description: 'Deterministic, cacheable listing over listed catalog services with an EBNF `filter`, `orderBy`, and `pageSize`/`pageToken`. Returns `{ items, total, pageToken }`. Public. Optional `Authorization: Bearer `: for an account that can use the Nevermined Subscription, each `nvm:catalog.endpoints[]` entry the subscription can pay carries `subscription`: `{ estimatedCreditsPerCall }`, an estimate, since each call is priced from what the merchant quotes for it (`POST /api/v1/router/subscription/quote` gives the exact credits). Send `Nevermined-Version: 1.91` or later: an older version reads it on no endpoint. No `subscription` field means credits are not offered for that endpoint. A missing or refused key is served the anonymous response, never a 401. A keyed read counts against the per-key rate limit of that key and is never shared-cached.'
operationId: ArdRegistryController_agents
parameters:
- name: filter
required: false
in: query
description: EBNF filter expression, e.g. "type = 'application/a2a-agent-card+json' AND updatedAt > '2026-01-01'".
schema:
type: string
- name: orderBy
required: false
in: query
description: 'Sort field + optional direction (one of: rankScore, updatedAt, createdAt, title). Omit it for the default curated ranking (tier, editorial sortWeight, then tier-neutral rankScore). No relevance sorting (that is /search).'
schema:
example: rankScore DESC
type: string
- name: pageSize
required: false
in: query
schema:
minimum: 1
maximum: 100
default: 20
type: number
- name: pageToken
required: false
in: query
description: Opaque pagination token.
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ArdListResponseDto'
'400':
description: Malformed filter/orderBy expression (INVALID_ARGUMENT).
'429':
description: Rate limit exceeded.
summary: ARD registry list (deterministic browse)
tags:
- ARD Registry
components:
schemas:
ArdExploreFacetResultDto:
type: object
properties:
buckets:
type: array
items:
$ref: '#/components/schemas/ArdExploreFacetBucketDto'
otherCount:
type: number
description: Matching entries in buckets beyond `limit`.
required:
- buckets
ArdSearchRequestDto:
type: object
properties:
funding:
type: string
enum:
- subscription
description: Only local services with at least one endpoint payable with credits. Filters before pagination; does not check the caller balance. Federation is disabled for this filter. When the subscription feature is disabled, returns an empty acknowledged result, not an error.
query:
$ref: '#/components/schemas/ArdSearchQueryDto'
federation:
type: string
enum:
- auto
- referrals
- none
default: auto
description: 'Federation mode (ARD §5.4). `none`: this registry only. `referrals`: also return the configured peer registries in `referrals` (no outbound call). `auto`: fan out to peers and merge into one ranked list — gated by config, off by default, degrades to `none`.'
pageSize:
type: number
default: 10
minimum: 1
maximum: 100
pageToken:
type: string
description: Opaque pagination token.
required:
- query
ArdListResponseDto:
type: object
properties:
items:
description: ARD entries; each carries at least `identifier`.
type: array
items:
type: object
total:
type: number
description: Total matching entries in the registry.
pageToken:
type: string
description: Token for the next page, when more entries exist.
required:
- items
- total
ArdSearchResultItemDto:
type: object
properties:
identifier:
type: string
example: urn:air:api.nevermined.app:service:webscrape-pro
semanticScore:
type: number
minimum: 0
maximum: 100
example: 95
description: Absolute cosine-similarity score (0–100). Present only when `rankingSource` is `semantic`.
lexicalScore:
type: number
minimum: 0
maximum: 100
example: 82
description: Per-result-set normalized full-text rank (0–100). Present only when `rankingSource` is `lexical`.
federatedScore:
type: number
minimum: 0
maximum: 100
description: Peer-provided relevance score, sanitized to 0–100 but not comparable across registries. Present only when `rankingSource` is `federated`.
rankingSource:
type: string
enum:
- semantic
- lexical
- federated
description: The scale used by this result item.
matchReason:
type: string
enum:
- semantic_similarity
- lexical_match
- federated_match
description: 'Closed match explanation: semantic similarity, a lexical full-text match, or a relayed peer match.'
source:
type: string
format: uri
example: https://api.nevermined.app/api/v1/ard
description: The registry endpoint where this entry was indexed.
displayName:
type: string
type:
type: string
url:
type: string
description:
type: string
tags:
type: array
items:
type: string
capabilities:
type: array
items:
type: string
updatedAt:
type: string
required:
- identifier
- rankingSource
- matchReason
- source
ArdExploreRequestDto:
type: object
properties:
query:
$ref: '#/components/schemas/ArdExploreQueryDto'
resultType:
$ref: '#/components/schemas/ArdExploreResultTypeDto'
required:
- resultType
ArdSearchResponseDto:
type: object
properties:
funding:
type: string
enum:
- subscription
description: Acknowledges the applied credits-only constraint. Absent on an unconstrained search.
results:
type: array
items:
$ref: '#/components/schemas/ArdSearchResultItemDto'
referrals:
description: Peer registries the caller may query next (ARD §5.4). Present only in `referrals` mode when at least one configured peer survives the self-origin guard; omitted otherwise.
type: array
items:
$ref: '#/components/schemas/ArdRegistryReferralDto'
pageToken:
type: string
description: Token for the next page, when more results exist.
required:
- results
ArdExploreFacetBucketDto:
type: object
properties:
value:
type: string
example: application/a2a-agent-card+json
count:
type: number
example: 389
required:
- value
- count
ArdExploreFacetRequestDto:
type: object
properties:
field:
type: string
example: type
description: 'Term path to aggregate. Phase 1 supports: type, publisher, pay:protocol, tags.'
limit:
type: number
default: 20
minimum: 1
description: Max buckets returned.
minCount:
type: number
default: 1
minimum: 0
description: Suppress buckets below this count.
required:
- field
ArdRegistryReferralDto:
type: object
properties:
identifier:
type: string
example: urn:air:nlweb.ai:registry:public
displayName:
type: string
example: Public Agent Finder
type:
type: string
example: application/ai-registry+json
description: Registry media type (`application/ai-registry` or `application/ai-registry+json`).
url:
type: string
format: uri
example: https://finder.nlweb.ai/search
required:
- identifier
- displayName
- type
- url
ArdExploreQueryDto:
type: object
properties:
text:
type: string
example: currency conversion
filter:
type: object
description: Same supported term set as /search (see resolveArdFilter).
example:
pay:protocol:
- x402
ArdSearchQueryDto:
type: object
properties:
text:
type: string
example: find me a weather lookup tool
description: Natural-language description of the need. Required for /search.
filter:
type: object
description: Structured constraints over the supported term set (type, tags, capabilities, publisher, pay:protocol, pay:currency, pay:network, pay:price). OR within a key, AND across keys. An unsupported key → 400 INVALID_ARGUMENT.
example:
type:
- application/a2a-agent-card+json
pay:protocol:
- x402
required:
- text
ArdExploreResultTypeDto:
type: object
properties:
facets:
type: array
items:
$ref: '#/components/schemas/ArdExploreFacetRequestDto'
required:
- facets
ArdExploreResponseDto:
type: object
properties:
resultType:
type: string
enum:
- facets
example: facets
facets:
type: object
description: Map of requested field → its facet result.
additionalProperties:
$ref: '#/components/schemas/ArdExploreFacetResultDto'
required:
- resultType
- facets
securitySchemes:
Authorization:
scheme: bearer
bearerFormat: JWT
type: http