Nevermined ARD Registry API

The ARD Registry API from Nevermined — 3 operation(s) for ard registry.

GitHub OpenAPI

Operations 3

POST /api/v1/ard/explore ARD registry explore (facets) #
GET /api/v1/ard/agents ARD registry list (deterministic browse) #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/nevermined-app:nevermined-app-ard-registry-api"
All apis
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.

Get an API 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 Specification

nevermined-app-ard-registry-api-openapi.yml Raw ↑
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