Router

Call a catalog service, paid with subscription credits

Call a catalog service and pay it with your Nevermined Subscription credits (mode B). Like POST /router/route, but Nevermined pays the merchant from its treasury and your subscription is charged the endpoint's rate in credits. There is no Delegation, no wallet to fund and no routing fee.

  • A slug, never a URL. Address the service by slug (+ path, search, method, headers, body). A url or a delegationId is refused (BCK.SUBSCRIPTION_ROUTER.0005), not ignored.
  • requestId is required (idempotency): a retry with the same id is never paid twice.
  • Only a merchant 2xx keeps the credits. They are reserved before the merchant is called and kept (Committed) only on a 2xx; anything else marks them for refund and they are returned (Refunded). Every refusal below happens before anything is reserved, signed or charged — except a 502, which can follow a payment.
  • Rails: x402 exact and MPP tempo merchants only.

For large or streamed responses, the streaming form is ALL /api/v1/router/subscription/svc/{slug}/{path} with an X-Router-Request-Id header; it answers with X-Router-Credits-Charged and X-Router-Credits-Status beside the X-Router-Payment-* headers, and refuses X-Router-Target-Url, X-Router-Target-Slug and X-Router-Delegation-Id.

Personal API keys only: the Nevermined Subscription belongs to a personal account, so call with a key that carries no organization tag and without X-Current-Org-Id. An OAuth-minted credential is refused (BCK.OAUTH.0030). Where the subscription is not available — on this deployment or to this account — it answers 404 BCK.SUBSCRIPTION_ACCESS.0001.

post/router/subscription/route

Request

  • Base URL: https://api.sandbox.nevermined.app/api/v1
  • URL: https://api.sandbox.nevermined.app/api/v1/router/subscription/route
  • Auth: HTTP bearer

Request body

slugstring required

Catalog slug of the service to call. Subscription credits pay catalog services only, addressed by slug; the Router resolves it to the merchant server-side.

pathstring

Subpath of the endpoint, appended to the resolved merchant URL (path segments only — //, .., a backslash or an embedded absolute URL is refused).

searchstring

Query string without the leading ?, attached to the resolved merchant URL.

method'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'

HTTP method to use for the upstream request.

headersobject

Headers to forward to the merchant (e.g. its own auth). Optional.

bodyunknown
credentialHeaderstring

Header the payment credential rides in on the paid hop, when the merchant needs its own Authorization too (a separate Payment header is the common one). Do not set it by default.

protocol'x402' | 'mpp'

Advisory: the Router detects the protocol from the merchant's 402.

requestIdstring required

Idempotency key — REQUIRED. At most one payment per (caller, requestId): a retry is never paid twice.

Example request

{
  "slug": "webscrape-pro",
  "path": "scrape",
  "search": "q=nevermined&limit=1",
  "credentialHeader": "Payment",
  "requestId": "scrape-example-com-1"
}

Response

The merchant's response (status, and body only when it delivered) plus the payment Nevermined made and the credits it cost.

statusnumber required

The merchant's HTTP status.

bodyunknown required
bodyEncoding'json' | 'text' | 'base64'

How body is represented. Absent when body is withheld.

contentTypestring nullable

The merchant's response media type, when body is relayed.

paidboolean required

Whether a payment was made (false when the service answered free).

Example response

{
  "contentType": "application/json",
  "payment": {
    "creditsCharged": 3
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.