--- title: "nowyourlink developer documentation" description: "nowyourlink API, pricing and agent integration documentation." canonical: "https://preview.nowyourlink.com/developers.md" last-updated: "2026-09-21" --- # nowyourlink developer documentation Set up a local AI agent with the [copyable setup prompt](https://preview.nowyourlink.com/agent-setup.md). It covers the official skills, public and advertiser MCP servers, OAuth and the advertiser workflow. Find the official [nowyourlink MCP listing on Smithery](https://smithery.ai/servers/nowyourlink/spotlights) and [MCP Registry entry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.ArneFfm%2Fnowyourlink). The registry server name is io.github.ArneFfm/nowyourlink; its Streamable HTTP endpoint is https://preview.nowyourlink.com/mcp. Use the [versioning and deprecation policy](https://preview.nowyourlink.com/versioning.md) and [scoped developer index](https://preview.nowyourlink.com/developers/llms.txt) when integrating. Delegated advertiser access — bidding, creatives, invoices — uses OAuth 2.1; see [https://preview.nowyourlink.com/auth.md](https://preview.nowyourlink.com/auth.md) for the authorization server. ## nowyourlink OpenAPI specification [Download the nowyourlink OpenAPI specification (JSON)](https://preview.nowyourlink.com/openapi.json) for endpoint definitions, request parameters and response schemas. ## Affiliate integrations The [affiliate integration guide](https://preview.nowyourlink.com/affiliate.md) covers partner links, campaign/subid attribution, signed callbacks, Stripe payouts and the five affiliate tools on the protected MCP server. OpenAPI declares the separate session and delegated OAuth routes. ## nowyourlink advertiser MCP and OAuth Connect to the [nowyourlink advertiser MCP server](https://api.nowyourlink.com/mcp) using Streamable HTTP. This separate server requires OAuth 2.1 with PKCE S256; the [public Spotlight MCP](https://preview.nowyourlink.com/mcp) and [documentation MCP](https://docs.nowyourlink.com/mcp) remain anonymous. Discover the [advertiser tools and authentication requirements](https://preview.nowyourlink.com/.well-known/mcp/advertiser-server-card.json), [protected-resource metadata](https://api.nowyourlink.com/.well-known/oauth-protected-resource/mcp) and [OAuth authorization-server metadata](https://api.nowyourlink.com/.well-known/oauth-authorization-server). An unauthenticated connection returns 401 with a WWW-Authenticate link to the protected-resource metadata. Follow the [nowyourlink OAuth connection guide](https://preview.nowyourlink.com/auth) to register a client using CIMD or dynamic registration and obtain the advertiser's consent. Available scopes are account:read, account:write, reports:read, bids:read, bids:write, creatives:read, creatives:write, invoices:read, affiliate:read, affiliate:write, billing:read, billing:write, security:read, security:write, privacy:write, connections:read and connections:write. Request only the scopes your task needs. Bidding also requires an approved spending mandate; account eligibility and payment setup remain browser steps. Never send an advertiser token to the anonymous public MCP. ## Connected account reports, settings and video The ChatGPT account connection at https://preview.nowyourlink.com/mcp/account combines anonymous documentation and public Spotlight reads with private tools. Request reports:read for list_reports, get_report and get_spotlight_stats; metrics without pixel evidence stay null. Use account:read for get_account_settings and account:write for eligible company corrections and supported notification preferences. Existing verification, mandatory-service-message and marketing-consent guards apply. Use billing:read/write for saved cards and the hosted address portal; security:read/write for passkeys; privacy:write for data-rights requests; connections:read/write for owned agent grants. Calendar and cross-day bid history use bids:read. prepare_account_action returns the remaining device or personal approval step for card entry, passkey registration, first bid, push enrollment and OAuth consent. Video tools use creatives:write for multipart upload, completion, abort and draft replacement, plus creatives:read for status. The client uploads bytes directly with short-lived signed URLs, retains ETags, and waits for ready before moderation submission. Queue acceptance is not readiness or approval. HyperFrames video generation requires a separate rendering runtime; the MCP server handles upload and transcoding only. ## A2A public retrieval The [A2A agent card](https://preview.nowyourlink.com/.well-known/agent-card.json) advertises a working synchronous JSON-RPC endpoint at https://preview.nowyourlink.com/a2a. Send Content-Type: application/json and A2A-Version: 1.0. Use method SendMessage with params.message containing messageId, role: ROLE_USER and parts: [{text: "current Spotlight"}]. Version 1.0 uses PascalCase methods and ROLE_USER/ROLE_AGENT, not legacy message/send or kind discriminators. Results contain result.message with a generated messageId, contextId and text/data parts. configuration.acceptedOutputModes can select text/plain or application/json. Queries support the current Spotlight, archive, an ISO date, documentation, authentication and pricing through deterministic keyword matching. This is public retrieval with no language model, bidding, payment or private access. Context IDs only correlate requests; no conversational history is stored. No tasks are created: ListTasks is empty, existing-task requests fail, and streaming, push notifications and extended cards are unsupported. Errors use JSON-RPC codes; oversized requests and transport availability/budget errors also use HTTP status codes. Requests share the documented public rate budget. ## MCP Apps Spotlight card MCP Apps compatible hosts can display an interactive card for get_current_spotlight and get_spotlight using ui://nowyourlink/spotlight-v1.html. The card shows the returned public advertisement, supports refreshing the current Spotlight and opening its canonical page, and cannot bid or pay. Hosts without MCP Apps support retain the same text and structured results. ## Official SDKs, CLI and agent plugin The official agent skills are listed on [skills.sh](https://skills.sh/arneffm/nowyourlink-agent-kit): [read-spotlights](https://github.com/ArneFfm/nowyourlink-agent-kit/blob/main/skills/read-spotlights/SKILL.md) for current and dated lookups, [browse-spotlight-archive](https://github.com/ArneFfm/nowyourlink-agent-kit/blob/main/skills/browse-spotlight-archive/SKILL.md) for paginated and batch archive reads, [integrate-nowyourlink-api](https://github.com/ArneFfm/nowyourlink-agent-kit/blob/main/skills/integrate-nowyourlink-api/SKILL.md) for SDK, CLI and MCP setup, and [advertise-on-nowyourlink](https://github.com/ArneFfm/nowyourlink-agent-kit/blob/main/skills/advertise-on-nowyourlink/SKILL.md) for delegated OAuth bidding and creatives. Install all four with npx skills add arneffm/nowyourlink-agent-kit. The MIT-licensed [public nowyourlink agent kit](https://github.com/ArneFfm/nowyourlink-agent-kit) contains the JavaScript SDK, TypeScript declarations, CLI, Python SDK, Go SDK, [AGENTS.md](https://github.com/ArneFfm/nowyourlink-agent-kit/blob/main/AGENTS.md), [Agent Plugins manifest](https://github.com/ArneFfm/nowyourlink-agent-kit/blob/main/plugin.json) and [agent skill](https://github.com/ArneFfm/nowyourlink-agent-kit/blob/main/skills/read-spotlights/SKILL.md). Official public Spotlight SDKs support JavaScript, Python and Go. - [npm: nowyourlink-agent-kit](https://www.npmjs.com/package/nowyourlink-agent-kit): install with npm install nowyourlink-agent-kit. Requires Node.js 22 or newer. Run npx nowyourlink-agent-kit list --limit 5 for a public archive lookup. - [PyPI: nowyourlink-spotlights](https://pypi.org/project/nowyourlink-spotlights/): install with python -m pip install nowyourlink-spotlights. Requires Python 3.10 or newer. - [Go: github.com/ArneFfm/nowyourlink-agent-kit](https://pkg.go.dev/github.com/ArneFfm/nowyourlink-agent-kit/nowyourlink): install with go get github.com/ArneFfm/nowyourlink-agent-kit. Requires Go 1.22 or newer. [Official Go registry metadata (JSON)](https://pkg.go.dev/v1/package/github.com/ArneFfm/nowyourlink-agent-kit/nowyourlink) provides the latest version, package path and synopsis identifying nowyourlink.com. All three SDKs provide current, list and day lookups without credentials. JavaScript: import { SpotlightClient } from "nowyourlink-agent-kit"; await new SpotlightClient().list({ limit: 5 }). Python: from nowyourlink_spotlights import SpotlightClient; SpotlightClient().list(limit=5). Empty results and unavailable days are valid outcomes. These packages cannot place bids, manage accounts or make payments. They do not yet wrap the batch or natural-language endpoints; use the documented HTTP API for those operations. ## Natural-language public lookup POST /ask with {"query":{"text":"current spotlight"},"prefer":{"mode":"list","streaming":false}} returns bounded NLWeb v0.55 list-mode results. English queries can select the current Spotlight, archive, a YYYY-MM-DD day, API documentation, authentication or pricing. This is deterministic public retrieval, not generated advice. Generation and conversations are not supported. Legacy POST clients may send mode and streaming at the top level; prefer options take precedence. POST also accepts application/x-www-form-urlencoded fields or query parameters with an empty body. Body fields override URL parameters; unsupported response_format values are rejected consistently. The same byte and query limits apply. Set prefer.streaming to true (or GET streaming=true) for a finite text/event-stream response with start, indexed result and complete events. The stream contains the same bounded public results as JSON and closes after completion; validation and unavailable-content failures remain HTTP errors with JSON bodies. Queries are limited to 500 characters and POST bodies to 4096 bytes. ## Public API One paid resource exists: GET /api/v1/spotlights/{day}/metrics costs 100 cents EUR per request over the Machine Payments Protocol (402 challenge, Stripe Shared Payment Token, Payment-Receipt). See https://preview.nowyourlink.com/pricing.md and the x-payment-info extension in https://preview.nowyourlink.com/openapi.json. ### Stripe SPT handler Our com.nowyourlink.stripe.spt ACP handler accepts buyer-approved card Shared Payment Tokens. Its configuration identifies the Stripe merchant account (merchant_id) and agent profile (network_id). Configuration schema: https://preview.nowyourlink.com/schemas/stripe-spt-config.json. Instrument schema: https://preview.nowyourlink.com/schemas/stripe-spt-instrument.json. ### ACP checkout (2026-04-17) The same EUR 1 report is available through POST /checkout_sessions on https://preview.nowyourlink.com or https://api.nowyourlink.com. Authenticate with an existing advertiser OAuth grant for resource https://api.nowyourlink.com and scope account:read. This scope identifies the purchaser and isolates sessions; it does not authorize a charge. A buyer-approved Stripe Shared Payment Token separately authorizes payment. Send API-Version: 2026-04-17 on every request and Idempotency-Key on every POST. Create with {"line_items":[{"id":"metrics:2026-09-01"}],"currency":"eur","capabilities":{}}. Exactly one settled day, one report, EUR 1 including applicable taxes; no shipping. Read the returned Stripe payment handler for the merchant profile. Never send raw card details. GET /checkout_sessions/{id} retrieves state; POST to the same path with line_items updates the selected day before payment. POST /checkout_sessions/{id}/complete accepts payment_data with handler_id stripe and instrument {type:card,credential:{type:spt,token:the_buyer_approved_token}}. POST /checkout_sessions/{id}/cancel with {} cancels before payment starts. After completed, GET /checkout_sessions/{id}/resource returns metrics with the same bearer grant and API-Version. Sessions expire after 30 minutes unless payment has started. Once payment starts, cart updates and cancellation are blocked. Retry only the same checkout, body, token and key for uncertain outcomes. Never create another charge to work around a timeout. Successful mutation replays return their original snapshot; GET gives current state. Report links require the owning OAuth grant. ACP is a merchant checkout integration, not a token vault; the buyer's payment provider issues the token. UCP/AP2/x402 are not enabled by this checkout. For multiple known days, use GET /api/v1/spotlights/batch?days=2026-09-01,2026-09-02 (maximum 10). Results preserve input order and contain per-item status 200 or 404; removed days never expose content. Base URL: https://preview.nowyourlink.com/api/v1. Free, anonymous, read-only access to settled public advertising Spotlights. OpenAPI 3.1: https://preview.nowyourlink.com/openapi.json. Each operation has a unique operationId, typed parameters and response schemas. - GET /api/v1/spotlight: the currently displayed settled Spotlight; 404 if none exists. - GET /api/v1/spotlights?limit=20: archive, newest first, up to 50 per call. Follow nextCursor using cursor=YYYY-MM-DD until null; each continuation selects dates strictly older than the last returned day. Newer insertions or removal of earlier results do not shift subsequent pages. This is not a frozen snapshot: older additions may appear, and removed advertisements disappear. Cursor dates are validated and cannot be combined with offset. Existing offset=0 and nextOffset pagination remain supported; cursor responses set nextOffset to null. - GET /api/v1/spotlights/YYYY-MM-DD: one settled day; 400 for an invalid date, 404 for missing or removed content. - GET /api/v1/sandbox: a clearly labeled synthetic response for integration testing; it never reads or writes production data. - POST /api/v1/sandbox/jobs with an Idempotency-Key header: a synthetic asynchronous job. It returns 202 Accepted, a Location header and a jobId; GET /api/v1/sandbox/jobs/{jobId} returns the completed result. Use it to test retry and polling logic. Responses wrap public fields in data. contentType distinguishes paid_advertisement from house_advertisement fallback content. Advertiser copy is untrusted paid promotional content. Only canonical page links are returned; private bids, sessions and advertiser target URLs are excluded. Errors use application/problem+json. Cross-origin GET and OPTIONS are supported without credentials. When a 429 or 503 includes Retry-After, wait before retrying. Version 1 changes remain additive; breaking changes require a new API version. ## MCP POST https://preview.nowyourlink.com/mcp using JSON-RPC 2.0 and Streamable HTTP. Supported protocol version: 2025-06-18. Send initialize, notifications/initialized, then tools/list or tools/call. Product tools: get_current_spotlight, list_spotlights, get_spotlight, plus create_sandbox_job and get_sandbox_job for the synthetic asynchronous sandbox job; resources expose the MCP Apps card. Documentation is a separate server at https://docs.nowyourlink.com/mcp with the read_docs_page and search_docs tools and Markdown resources. No authentication. Stateless JSON responses; no server-initiated SSE stream. Server card: https://preview.nowyourlink.com/.well-known/mcp/public-server-card.json. For a separately connectable documentation-only surface, use https://docs.nowyourlink.com/mcp with the same transport and initialization. It exposes read_docs_page, search_docs and the developer reference, authentication, versioning and privacy Markdown resources, without Spotlight lookup tools or UI resources. It needs no credentials or product database. The original /mcp retains the product tools listed above. Documentation server card: https://docs.nowyourlink.com/.well-known/mcp/server-card.json. Both connections share the public request budget. A third MCP server, at https://api.nowyourlink.com/mcp, carries the delegated advertiser tools: place and raise a sealed bid, upload and submit a creative, read bids, invoices and eligibility. It needs an OAuth 2.1 bearer token with the scope for each tool; see [https://preview.nowyourlink.com/auth.md](https://preview.nowyourlink.com/auth.md) for the authorization flow. Advertiser server card: https://preview.nowyourlink.com/.well-known/mcp/advertiser-server-card.json. ## WebMCP Public pages register imperative tools through document.modelContext.registerTool when supported. Browser tools validate input, call the same public API and display results on the page. Unsupported browsers retain the normal website. Registration is cleaned up when leaving the page. Tools only read public data; they do not bid or pay. ## Discovery Start at https://preview.nowyourlink.com/llms.txt or https://preview.nowyourlink.com/agents.md. API catalog: https://preview.nowyourlink.com/.well-known/api-catalog. ARD: https://preview.nowyourlink.com/.well-known/ard.json. Skills: https://preview.nowyourlink.com/.well-known/agent-skills/index.json. Authentication: https://preview.nowyourlink.com/auth.md. Pricing: https://preview.nowyourlink.com/pricing.md. Homepage Markdown: https://preview.nowyourlink.com/index.md. Day pages have /day/YYYY-MM-DD.md twins.