--- title: "nowyourlink developer documentation" description: "Public read-only nowyourlink Spotlight integration and documentation." canonical: "https://nowyourlink.com/developers.md" last-updated: "2026-09-07" --- # nowyourlink developer documentation 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://nowyourlink.com/mcp. Use the [versioning and deprecation policy](https://nowyourlink.com/versioning.md) and [scoped developer index](https://nowyourlink.com/developers/llms.txt) when integrating. ## A2A public retrieval The [A2A agent card](https://nowyourlink.com/.well-known/agent-card.json) advertises a working synchronous JSON-RPC endpoint at https://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 [read-spotlights agent skill](https://skills.sh/arneffm/nowyourlink-agent-kit/read-spotlights) provides public read-only integration instructions. The MIT-licensed [public nowyourlink agent kit](https://github.com/ArneFfm/nowyourlink-agent-kit) contains the JavaScript SDK, TypeScript declarations, CLI, Python 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). - [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. Both 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 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://nowyourlink.com/api/v1. Free, anonymous, read-only access to settled public advertising Spotlights. OpenAPI 3.1: https://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. 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://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. Tools: get_current_spotlight, list_spotlights, get_spotlight, read_agent_docs. Resources expose the agent guide, auth guide, pricing and API reference. No authentication. Stateless JSON responses; no server-initiated SSE stream. Server card: https://nowyourlink.com/.well-known/mcp/server-card.json. For a separately connectable documentation-only surface, use https://nowyourlink.com/mcp/docs with the same transport and initialization. It exposes only read_agent_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 all four tools. Documentation server card: https://nowyourlink.com/.well-known/mcp/docs-server-card.json. Both connections share the public request budget. ## 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://nowyourlink.com/llms.txt or https://nowyourlink.com/agents.md. API catalog: https://nowyourlink.com/.well-known/api-catalog. ARD: https://nowyourlink.com/.well-known/ard.json. Skills: https://nowyourlink.com/.well-known/agent-skills/index.json. Authentication: https://nowyourlink.com/auth.md. Pricing: https://nowyourlink.com/pricing.md. Homepage Markdown: https://nowyourlink.com/index.md. Day pages have /day/YYYY-MM-DD.md twins.