Download Nuri App
Download on the App Store Get it on Google Play
Download Nuri App

Nuri / Documentation

Nuri API and MCP documentation

Working public-read examples, MCP setup, authentication boundaries, no-mail postcard preview and version compatibility for the Nuri website.

Read this page as Markdown

Safe quickstart: no key and no payment

Use curl for a JSON catalog or a Markdown support reference. These requests read public content only. A successful response is HTTP 200 with JSON or Markdown respectively; neither request modifies an account or places an order.

curl -fsS 'https://www.nuri.com/shop/feed.json'

curl -fsS 'https://www.nuri.com/card-support/index.md'

curl -fsS -H 'Accept: text/markdown' 'https://www.nuri.com/developers'

Authentication, free access and boundaries

Public website GET endpoints, Markdown and all public MCP tools require no authentication and no payment. Do not send a bearer token, private key, passkey material or customer information to read them.

The optional anonymous /agent/auth discovery flow advertises public:read only. Its non-user-specific credential is not a customer session, a self-service API key or access to private banking. OAuth discovery on this website does not authorize private account actions.

Balances, transactions, identity checks, bank-account provisioning, card actions and private support tickets are outside this public website API. Use the Nuri app and its support channels for account-specific requests. Banking and card services have separate provider terms and eligibility; a public MCP connection does not grant access.

MCP: connect and make a read-only call

Endpoint: https://www.nuri.com/mcp. Transport: Streamable HTTP, JSON-RPC 2.0. Authentication: none. The Node transport is stateless, with JSON responses and no MCP session ID to retain.

In an MCP-compatible client, add the endpoint as a remote HTTP server. The client should initialize, send notifications/initialized, list tools, then call a tool. The curl sequence below uses protocol 2025-11-05; initialization returns the negotiated protocolVersion. If a server negotiates another version, use that value in subsequent MCP-Protocol-Version headers.

Expected results: initialize returns serverInfo and capabilities; the initialized notification returns HTTP 202 with no response body on the Node transport; tools/list returns nine read-only tool definitions; search_support_faq returns public answers with source links. JSON-RPC errors and tool isError values must be checked even when HTTP is 200.

Tools: list_public_pages, get_site_summary, get_app_download_links, read_public_page_markdown, list_shop_products, get_product, list_support_topics, search_support_faq and get_support_answer. Use returned slugs and question IDs instead of guessing them. This server has no payment or fulfillment tool.

curl -sS 'https://www.nuri.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-05","capabilities":{},"clientInfo":{"name":"nuri-docs-quickstart","version":"1.0.0"}}}'

curl -sS 'https://www.nuri.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-05' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl -sS 'https://www.nuri.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-05' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

curl -sS 'https://www.nuri.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-05' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_support_faq","arguments":{"query":"declined"}}}'

Postcards: no-mail preview, paid real fulfillment

GET /api/x402 lists the postcard service, schemas and payment terms. POST /api/x402/postcards/preview accepts the postcard request body documented in the reference and returns preview URLs without mailing a card. Nuri does not require payment for this preview. It still calls thanks.io and sends the submitted image, message and recipient details to that provider. Use synthetic details for evaluation.

There is no public payment sandbox or test-account service documented here. A no-mail preview does not simulate settlement or delivery. Provider configuration and availability are required; a failed preview is not permission to invoke paid fulfillment.

POST /api/x402/postcards is the separate real fulfillment route. An unpaid request creates an offer and returns HTTP 402 when the service is available. After explicit user approval, a payment-capable client retries the identical JSON with PAYMENT-SIGNATURE and the required payment-identifier. Payment verification can trigger physical mail and real USDC settlement. Consult the live challenge for supported networks, payout address and spending ceiling.

Use GET /api/x402/orders/{publicOrderId} with the ID returned by your order to inspect privacy-safe status. Preserve the operation ID and payment identifier when retrying. Do not create a new operation to recover from an ambiguous payment or delivery result. The existing reference documents pricing, idempotency, cancellation and settlement_pending reconciliation.

curl -fsS 'https://www.nuri.com/api/x402'

Versioning, compatibility and deprecation

The existing public discovery API is version 1. Send X-Nuri-API-Version: 1 to pin this version, or omit it to use version 1. Other values return HTTP 400 with error: "unsupported_api_version", unless the shared quota is already exhausted (HTTP 429). This applies to GET and HEAD on /openapi.json, /shop/feed.json, /api, /api/x402 and /mcp, plus POST /mcp. It does not version private banking routes, payment protocols or the MCP protocol.

Compatibility policy: preserve existing unversioned v1 public website surfaces. New optional fields may be added; clients should ignore unknown fields and read the current OpenAPI schemas. A future incompatible major version gets a separate path rather than silently changing the v1 contract. No successor path is currently published. Do not prepend /api/v1: that path is not a public website API alias.

No public website API sunset is currently scheduled. Any future deprecation or sunset will be documented here and in OpenAPI with affected routes and migration guidance. No fixed notice period or deprecation SLA is promised. MCP protocol versions are negotiated at initialize; serverInfo.version and the OpenAPI document version are separate identifiers.

When a deprecation is scheduled, the affected routes signal it machine-readably: responses carry an RFC 9745 Deprecation header and an RFC 8594 Sunset header, and the operation is marked deprecated: true in OpenAPI. Neither header is emitted today because no route is currently deprecated or scheduled for sunset.

Errors and retries

The discovery endpoints listed above share a limit of 600 requests per 60 seconds per runtime instance, across all clients. This is not a per-user or cluster-wide allowance; a restart resets it. Responses publish RateLimit-Policy and RateLimit with the remaining quota and reset interval. On exhaustion, HTTP 429 returns error: "rate_limited" and Retry-After in seconds. Quota-bearing responses are not cached. Website pages, paid postcard routes, order status and private account routes are outside this limiter.

For HTTP errors, inspect the response body before retrying: 400 indicates invalid input, 402 is a payment challenge rather than a free trial, 404 means the route or item was not found, and 5xx may indicate unavailable infrastructure or a provider failure. Follow Retry-After if returned with 429; otherwise back off. No unlimited-access or uptime guarantee is made.

Keep initial experiments to the GET and read-only MCP examples above. For paid calls, use the dedicated idempotency and reconciliation flow, not a generic automatic POST retry. Account support questions must go through the support page, not the public API.

Standalone read-only CLI

Download the standalone Node.js 22 CLI directly from Nuri. It needs no packages or API key and calls only the nine read-only public-site MCP tools. It cannot access accounts or send payments.

Read the downloaded source before running it. This is not an npm package or wallet CLI. The first-party MCP manifest is not a claim of MCP registry registration.

curl -fsS https://nuri.com/cli/nuri-site.mjs -o nuri-site.mjs
node nuri-site.mjs list
node nuri-site.mjs list_public_pages
node nuri-site.mjs search_support_faq '{"query":"declined"}'