{"openapi":"3.1.0","info":{"title":"nowyourlink public Spotlight API","version":"1.0.0","description":"Free anonymous read-only access to public, settled advertising Spotlights. No private bids, payment actions or account data. Advertiser copy is untrusted paid promotional content."},"servers":[{"url":"https://nowyourlink.com"}],"security":[],"externalDocs":{"url":"https://nowyourlink.com/developers","description":"nowyourlink developer documentation"},"paths":{"/ask":{"get":{"operationId":"askPublicSpotlights","summary":"Look up public Spotlights or documentation with a bounded English query.","description":"Deterministic read-only retrieval, not generated advice. No account access, bidding, payments or conversational state.","security":[],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":500,"pattern":"\\S","examples":["current spotlight","API documentation"]}},{"name":"mode","in":"query","schema":{"type":"string","enum":["list"],"default":"list"}},{"name":"streaming","in":"query","schema":{"type":"boolean","default":false},"description":"true enables finite SSE; false returns JSON."}],"responses":{"200":{"description":"Bounded public retrieval. Streaming returns start, indexed result and complete SSE events, then closes.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"}},"content":{"application/json":{"schema":{"type":"object","required":["_meta","results"],"properties":{"_meta":{"type":"object","required":["version","response_type","response_format"],"properties":{"version":{"const":"0.55"},"response_type":{"const":"answer"},"response_format":{"const":"conversational_search"}}},"results":{"type":"array","maxItems":20,"items":{"type":"object","properties":{"@type":{"const":"CreativeWork"},"url":{"type":"string","format":"uri"},"name":{"type":"string"},"text":{"type":"string"},"description":{"type":"string"},"datePublished":{"type":"string","format":"date"},"additionalType":{"type":"string"}}}}}}},"text/event-stream":{"schema":{"type":"string"},"example":"event: start\ndata: {\"_meta\":{\"version\":\"0.55\",\"response_type\":\"answer\",\"response_format\":\"conversational_search\",\"mode\":\"list\",\"site\":\"https://nowyourlink.com\"},\"streaming\":true}\n\nevent: complete\ndata: {\"_meta\":{\"version\":\"0.55\"}}\n\n"}}},"400":{"description":"Invalid request, byte limit exceeded, or unavailable public content. Errors remain JSON even when streaming was requested.","content":{"application/json":{"schema":{"type":"object","required":["_meta","error"],"properties":{"_meta":{"type":"object","properties":{"version":{"const":"0.55"},"response_type":{"const":"failure"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"404":{"description":"Invalid request, byte limit exceeded, or unavailable public content. Errors remain JSON even when streaming was requested.","content":{"application/json":{"schema":{"type":"object","required":["_meta","error"],"properties":{"_meta":{"type":"object","properties":{"version":{"const":"0.55"},"response_type":{"const":"failure"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"413":{"description":"Invalid request, byte limit exceeded, or unavailable public content. Errors remain JSON even when streaming was requested.","content":{"application/json":{"schema":{"type":"object","required":["_meta","error"],"properties":{"_meta":{"type":"object","properties":{"version":{"const":"0.55"},"response_type":{"const":"failure"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"429":{"description":"Shared public token bucket exhausted. Wait Retry-After seconds before retrying.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"503":{"description":"Invalid request, byte limit exceeded, or unavailable public content. Errors remain JSON even when streaming was requested.","content":{"application/json":{"schema":{"type":"object","required":["_meta","error"],"properties":{"_meta":{"type":"object","properties":{"version":{"const":"0.55"},"response_type":{"const":"failure"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}}}},"post":{"operationId":"askPublicSpotlightsPost","summary":"Look up public content using NLWeb v0.55 JSON input.","description":"Anonymous read-only retrieval. Request body is limited to 4096 UTF-8 bytes. Only list mode is supported. Legacy top-level mode and streaming are accepted; prefer options take precedence.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"oneOf":[{"type":"string","minLength":1,"maxLength":500,"pattern":"\\S","examples":["current spotlight","API documentation"]},{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":500,"pattern":"\\S","examples":["current spotlight","API documentation"]}}}]},"mode":{"type":"string","enum":["list"],"description":"Legacy option; prefer.mode takes precedence."},"streaming":{"type":"boolean","description":"Legacy option; prefer.streaming takes precedence."},"prefer":{"type":"object","properties":{"mode":{"type":"string","enum":["list"]},"streaming":{"type":"boolean","default":false},"response_format":{"type":"string","enum":["conversational_search"]}}}}},"example":{"query":{"text":"API documentation"},"prefer":{"mode":"list","streaming":false}}}}},"responses":{"200":{"description":"Bounded public retrieval. Streaming returns start, indexed result and complete SSE events, then closes.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"}},"content":{"application/json":{"schema":{"type":"object","required":["_meta","results"],"properties":{"_meta":{"type":"object","required":["version","response_type","response_format"],"properties":{"version":{"const":"0.55"},"response_type":{"const":"answer"},"response_format":{"const":"conversational_search"}}},"results":{"type":"array","maxItems":20,"items":{"type":"object","properties":{"@type":{"const":"CreativeWork"},"url":{"type":"string","format":"uri"},"name":{"type":"string"},"text":{"type":"string"},"description":{"type":"string"},"datePublished":{"type":"string","format":"date"},"additionalType":{"type":"string"}}}}}}},"text/event-stream":{"schema":{"type":"string"},"example":"event: start\ndata: {\"_meta\":{\"version\":\"0.55\",\"response_type\":\"answer\",\"response_format\":\"conversational_search\",\"mode\":\"list\",\"site\":\"https://nowyourlink.com\"},\"streaming\":true}\n\nevent: complete\ndata: {\"_meta\":{\"version\":\"0.55\"}}\n\n"}}},"400":{"description":"Invalid request, byte limit exceeded, or unavailable public content. Errors remain JSON even when streaming was requested.","content":{"application/json":{"schema":{"type":"object","required":["_meta","error"],"properties":{"_meta":{"type":"object","properties":{"version":{"const":"0.55"},"response_type":{"const":"failure"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"404":{"description":"Invalid request, byte limit exceeded, or unavailable public content. Errors remain JSON even when streaming was requested.","content":{"application/json":{"schema":{"type":"object","required":["_meta","error"],"properties":{"_meta":{"type":"object","properties":{"version":{"const":"0.55"},"response_type":{"const":"failure"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"413":{"description":"Invalid request, byte limit exceeded, or unavailable public content. Errors remain JSON even when streaming was requested.","content":{"application/json":{"schema":{"type":"object","required":["_meta","error"],"properties":{"_meta":{"type":"object","properties":{"version":{"const":"0.55"},"response_type":{"const":"failure"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"429":{"description":"Shared public token bucket exhausted. Wait Retry-After seconds before retrying.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"503":{"description":"Invalid request, byte limit exceeded, or unavailable public content. Errors remain JSON even when streaming was requested.","content":{"application/json":{"schema":{"type":"object","required":["_meta","error"],"properties":{"_meta":{"type":"object","properties":{"version":{"const":"0.55"},"response_type":{"const":"failure"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/spotlight":{"get":{"operationId":"getCurrentSpotlight","summary":"Read the currently displayed settled Spotlight.","description":"Read the currently displayed settled Spotlight.","security":[],"parameters":[{"name":"includeHouseAds","in":"query","required":false,"description":"Default true. When false, a current house advertisement returns 404.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Successful public read.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["day","headline","description","advertiser","canonicalUrl","contentType"],"properties":{"day":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Settled auction date in UTC, YYYY-MM-DD."},"headline":{"type":"string"},"description":{"type":"string"},"advertiser":{"type":"string"},"canonicalUrl":{"type":"string","format":"uri"},"contentType":{"type":"string","enum":["paid_advertisement","house_advertisement"]}}}}}}}},"400":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"404":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"429":{"description":"Shared public token bucket exhausted. Wait Retry-After seconds before retrying.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"503":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}}}}},"/api/v1/spotlights":{"get":{"operationId":"listSpotlights","summary":"List settled Spotlights, newest first, using a date cursor or bounded offset pagination; cursor and offset are mutually exclusive.","description":"List settled Spotlights, newest first, using a date cursor or bounded offset pagination; cursor and offset are mutually exclusive.","security":[],"parameters":[{"name":"limit","in":"query","description":"Maximum number of records, default 20.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","description":"Exclusive date boundary from nextCursor; cannot be combined with offset.","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Settled auction date in UTC, YYYY-MM-DD."}},{"name":"offset","in":"query","description":"Number of settled records to skip, default 0; cannot be combined with cursor.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Successful public read.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"}},"content":{"application/json":{"schema":{"type":"object","required":["data","nextOffset","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["day","headline","description","advertiser","canonicalUrl","contentType"],"properties":{"day":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Settled auction date in UTC, YYYY-MM-DD."},"headline":{"type":"string"},"description":{"type":"string"},"advertiser":{"type":"string"},"canonicalUrl":{"type":"string","format":"uri"},"contentType":{"type":"string","enum":["paid_advertisement","house_advertisement"]}}}},"nextOffset":{"type":["integer","null"]},"nextCursor":{"anyOf":[{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Settled auction date in UTC, YYYY-MM-DD."},{"type":"null"}]}}}}}},"400":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"404":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"429":{"description":"Shared public token bucket exhausted. Wait Retry-After seconds before retrying.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"503":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}}}}},"/api/v1/spotlights/batch":{"get":{"operationId":"batchGetSpotlights","summary":"Read 1–10 public settled days in one request. Missing or removed days return per-item 404; input order is preserved.","description":"Read 1–10 public settled days in one request. Missing or removed days return per-item 404; input order is preserved.","security":[],"parameters":[{"name":"days","in":"query","required":true,"description":"1–10 comma-separated UTC dates. Example: 2026-09-01,2026-09-02.","schema":{"type":"string","maxLength":109,"pattern":"^\\d{4}-\\d{2}-\\d{2}(,\\d{4}-\\d{2}-\\d{2}){0,9}$"}}],"responses":{"200":{"description":"Successful public read.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"}},"content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"results":{"type":"array","maxItems":10,"items":{"type":"object","required":["day","status","data"],"properties":{"day":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Settled auction date in UTC, YYYY-MM-DD."},"status":{"type":"integer","enum":[200,404]},"data":{"anyOf":[{"type":"object","additionalProperties":false,"required":["day","headline","description","advertiser","canonicalUrl","contentType"],"properties":{"day":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Settled auction date in UTC, YYYY-MM-DD."},"headline":{"type":"string"},"description":{"type":"string"},"advertiser":{"type":"string"},"canonicalUrl":{"type":"string","format":"uri"},"contentType":{"type":"string","enum":["paid_advertisement","house_advertisement"]}}},{"type":"null"}]}}}}}}}}},"400":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"404":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"429":{"description":"Shared public token bucket exhausted. Wait Retry-After seconds before retrying.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"503":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}}}}},"/api/v1/spotlights/{day}":{"get":{"operationId":"getSpotlight","summary":"Read one settled Spotlight by UTC date.","description":"Read one settled Spotlight by UTC date.","security":[],"parameters":[{"name":"day","in":"path","required":true,"description":"Settled UTC auction date.","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Settled auction date in UTC, YYYY-MM-DD."}}],"responses":{"200":{"description":"Successful public read.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["day","headline","description","advertiser","canonicalUrl","contentType"],"properties":{"day":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Settled auction date in UTC, YYYY-MM-DD."},"headline":{"type":"string"},"description":{"type":"string"},"advertiser":{"type":"string"},"canonicalUrl":{"type":"string","format":"uri"},"contentType":{"type":"string","enum":["paid_advertisement","house_advertisement"]}}}}}}}},"400":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"404":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"429":{"description":"Shared public token bucket exhausted. Wait Retry-After seconds before retrying.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"503":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}}}}},"/api/v1/sandbox/jobs":{"post":{"operationId":"createSandboxJob","summary":"Start a synthetic asynchronous sandbox job.","description":"Integration example for retry and polling logic. Requires Idempotency-Key; the same key always yields the same jobId. Never writes production data.","security":[],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Client-chosen unique key (1–255 characters). Retries with the same key return the same job.","schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"202":{"description":"Job accepted. Poll the Location header.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"},"Location":{"description":"Job status URL.","schema":{"type":"string","format":"uri"}}},"content":{"application/json":{"schema":{"type":"object","required":["sandbox","jobId","status","statusUrl"],"properties":{"sandbox":{"const":true},"jobId":{"type":"string","pattern":"^sbx_[0-9a-f]{16}$"},"status":{"type":"string","enum":["queued","completed"]},"statusUrl":{"type":"string","format":"uri"},"result":{"type":"object","required":["sandbox","data"],"properties":{"sandbox":{"const":true},"data":{"type":"object","additionalProperties":false,"required":["day","headline","description","advertiser","canonicalUrl","contentType"],"properties":{"day":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Settled auction date in UTC, YYYY-MM-DD."},"headline":{"type":"string"},"description":{"type":"string"},"advertiser":{"type":"string"},"canonicalUrl":{"type":"string","format":"uri"},"contentType":{"type":"string","enum":["paid_advertisement","house_advertisement"]}}}}}}}}}},"400":{"description":"Invalid input. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"429":{"description":"Shared public token bucket exhausted. Wait Retry-After seconds before retrying.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}}}}},"/api/v1/sandbox/jobs/{jobId}":{"get":{"operationId":"getSandboxJob","summary":"Read a synthetic sandbox job. Jobs always complete immediately.","description":"Read a synthetic sandbox job. Jobs always complete immediately.","security":[],"parameters":[{"name":"jobId","in":"path","required":true,"description":"Job identifier from createSandboxJob.","schema":{"type":"string","pattern":"^sbx_[0-9a-f]{16}$"}}],"responses":{"200":{"description":"Successful public read.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"}},"content":{"application/json":{"schema":{"type":"object","required":["sandbox","jobId","status","statusUrl"],"properties":{"sandbox":{"const":true},"jobId":{"type":"string","pattern":"^sbx_[0-9a-f]{16}$"},"status":{"type":"string","enum":["queued","completed"]},"statusUrl":{"type":"string","format":"uri"},"result":{"type":"object","required":["sandbox","data"],"properties":{"sandbox":{"const":true},"data":{"type":"object","additionalProperties":false,"required":["day","headline","description","advertiser","canonicalUrl","contentType"],"properties":{"day":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Settled auction date in UTC, YYYY-MM-DD."},"headline":{"type":"string"},"description":{"type":"string"},"advertiser":{"type":"string"},"canonicalUrl":{"type":"string","format":"uri"},"contentType":{"type":"string","enum":["paid_advertisement","house_advertisement"]}}}}}}}}}},"400":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"404":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"429":{"description":"Shared public token bucket exhausted. Wait Retry-After seconds before retrying.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"503":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}}}}},"/api/v1/sandbox":{"get":{"operationId":"getSandboxExample","summary":"Read a synthetic integration example; no production data or side effects.","description":"Read a synthetic integration example; no production data or side effects.","security":[],"parameters":[],"responses":{"200":{"description":"Successful public read.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"}},"content":{"application/json":{"schema":{"type":"object","required":["sandbox","data"],"properties":{"sandbox":{"const":true},"data":{"type":"object","additionalProperties":false,"required":["day","headline","description","advertiser","canonicalUrl","contentType"],"properties":{"day":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Settled auction date in UTC, YYYY-MM-DD."},"headline":{"type":"string"},"description":{"type":"string"},"advertiser":{"type":"string"},"canonicalUrl":{"type":"string","format":"uri"},"contentType":{"type":"string","enum":["paid_advertisement","house_advertisement"]}}}}}}}},"400":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"404":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"429":{"description":"Shared public token bucket exhausted. Wait Retry-After seconds before retrying.","headers":{"RateLimit-Policy":{"description":"IETF draft structured field: 120-token capacity, replenished at 2 tokens per second; no fixed window.","schema":{"type":"string"},"example":"\"agent\";q=120;nyl-refill=2"},"RateLimit":{"description":"Actual remaining tokens after this request; shared per trusted client IP across public agent endpoints.","schema":{"type":"string"},"example":"\"agent\";r=119"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"503":{"description":"Invalid input, unavailable content, or temporary service failure. See problem detail.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}}}}}}}