{"openapi":"3.1.0","info":{"title":"LKJ Agent Link API","version":"0.7.0","description":"Create a public four-digit short link for a TV, phone or computer without an account, API key or CAPTCHA. Public beta with fair-use quotas. Use only public, non-sensitive websites. Codes are guessable and checks cannot guarantee safety."},"servers":[{"url":"https://lkj.cx"},{"url":"https://lkj.st"}],"security":[],"externalDocs":{"url":"https://lkj.cx/developers","description":"Usage, limits, retry behavior and TV instructions"},"paths":{"/api/v1/links":{"post":{"operationId":"createLkjTvLink","summary":"Create a four-digit code for opening a public website on another device","description":"Call only when the user asks to share a website. Send a new random Idempotency-Key for each new link. Reuse that key and the exact URL for network/error retries; concurrent retries cannot allocate two codes. Successful requests are replayable for at least 24 hours, but code availability can end sooner. Do not reuse a key for a different URL. Return code, short_url, expiry and TV instructions. The returned URLs are previews; do not follow /CODE/open automatically. An HTTP-capable agent is required; read-only web search cannot call POST APIs.","security":[],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"A fresh random UUID, preserved unchanged for retries of this URL. Never reuse for a new logical request.","schema":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","minLength":1,"maxLength":4096,"description":"Public HTTP(S) website address; a bare domain defaults to HTTPS. No credentials, IP addresses, custom ports, private networks or LKJ destinations."}}},"example":{"url":"https://example.com/"}}}},"responses":{"200":{"description":"Existing successful request replayed, without extending expiry or counting an opening.","content":{"application/json":{"schema":{"type":"object","required":["code","short_url","tv_url","tv_home_url","expires_at","expires_in_seconds","expiry_policy","instructions","safety_note"],"properties":{"code":{"type":"string","pattern":"^[0-9]{4}$","description":"Four digits; preserve leading zeros."},"short_url":{"type":"string","format":"uri","description":"Public destination preview with a version parameter. Preserve the complete URL, including v, so an old saved link cannot open a replacement destination."},"tv_url":{"type":"string","format":"uri"},"tv_home_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"expires_in_seconds":{"type":"integer","minimum":0},"expiry_policy":{"type":"string"},"instructions":{"type":"string"},"safety_note":{"type":"string"}}}}}},"201":{"description":"Code created; a concurrent retry may return the same code.","content":{"application/json":{"schema":{"type":"object","required":["code","short_url","tv_url","tv_home_url","expires_at","expires_in_seconds","expiry_policy","instructions","safety_note"],"properties":{"code":{"type":"string","pattern":"^[0-9]{4}$","description":"Four digits; preserve leading zeros."},"short_url":{"type":"string","format":"uri","description":"Public destination preview with a version parameter. Preserve the complete URL, including v, so an old saved link cannot open a replacement destination."},"tv_url":{"type":"string","format":"uri"},"tv_home_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"expires_in_seconds":{"type":"integer","minimum":0},"expiry_policy":{"type":"string"},"instructions":{"type":"string"},"safety_note":{"type":"string"}}}}}},"400":{"description":"Invalid request or URL","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"403":{"description":"Cross-origin browser request forbidden","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"405":{"description":"Use POST; GET, HEAD and OPTIONS never create a code.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"409":{"description":"Idempotency key used for another URL","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"410":{"description":"Original code expired, removed or blocked","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"413":{"description":"Request exceeds 8192 bytes","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"415":{"description":"JSON Content-Type required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"422":{"description":"Destination blocked","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"429":{"description":"Rate or daily quota reached; obey Retry-After","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds before retrying."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"Creation paused or checks temporarily unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}}}