{"openapi":"3.0.3","info":{"title":"y.hn API","version":"1.0.0","description":"Short-link platform. Authenticate with the `x-api-key` header (generate one at https://y.hn/dashboard/settings).","contact":{"name":"y.hn support","email":"support@y.hn","url":"https://y.hn"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://y.hn/api","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Generate at https://y.hn/dashboard/settings."}},"schemas":{"Link":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"targetUrl":{"type":"string","format":"uri"},"shortUrl":{"type":"string","format":"uri"},"title":{"type":"string","nullable":true},"clicks":{"type":"integer"},"password":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"maxClicks":{"type":"integer","nullable":true},"fallbackUrl":{"type":"string","nullable":true},"archived":{"type":"boolean"},"suspicious":{"type":"boolean"},"folderId":{"type":"string","nullable":true},"ogTitle":{"type":"string","nullable":true},"ogDescription":{"type":"string","nullable":true},"ogImage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreateLinkInput":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"customSlug":{"type":"string","description":"a-z0-9- only. ≥6 chars on free; shorter requires Pro+."},"password":{"type":"string","description":"Pro+ only."},"expiresAt":{"type":"string","format":"date-time","description":"Pro+ only; free auto-expires in 1 year."},"fallbackUrl":{"type":"string","format":"uri"},"maxClicks":{"type":"integer","minimum":1},"ogTitle":{"type":"string"},"ogDescription":{"type":"string"},"ogImage":{"type":"string","format":"uri"},"tagIds":{"type":"array","items":{"type":"string"}}}},"UpdateLinkInput":{"type":"object","properties":{"targetUrl":{"type":"string","format":"uri"},"password":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"fallbackUrl":{"type":"string","nullable":true},"maxClicks":{"type":"integer","nullable":true},"ogTitle":{"type":"string","nullable":true},"ogDescription":{"type":"string","nullable":true},"ogImage":{"type":"string","nullable":true},"archived":{"type":"boolean"},"folderId":{"type":"string","nullable":true}}},"Folder":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"_count":{"type":"object","properties":{"links":{"type":"integer"}}}}},"Tag":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["create","click","expire","delete"]}},"secret":{"type":"string","description":"HMAC-SHA256 secret. Verify using x-yhn-signature header."},"createdAt":{"type":"string","format":"date-time"}}},"ConversionGoal":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"totalConversions":{"type":"integer"},"totalRevenue":{"type":"number"}}},"Domain":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"verified":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Authenticated but not allowed (banned, plan gate, content blocked).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit hit (10/min, 20/hour, 25/month free).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/settings/api-key":{"get":{"operationId":"whoami","summary":"Verify API key, return account info.","tags":["Account"],"responses":{"200":{"description":"Valid key.","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"email":{"type":"string","format":"email"},"plan":{"type":"string","enum":["free","pro","business"]},"name":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/links":{"get":{"operationId":"listLinks","summary":"List links, paginated.","tags":["Links"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"folderId","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated link list.","content":{"application/json":{"schema":{"type":"object","properties":{"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}},"total":{"type":"integer"},"page":{"type":"integer"},"totalPages":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"operationId":"createLink","summary":"Create a short link.","tags":["Links"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLinkInput"}}}},"responses":{"200":{"description":"Link created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"shortUrl":{"type":"string","format":"uri"},"targetUrl":{"type":"string","format":"uri"}}}}}},"400":{"description":"Invalid URL or slug."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Slug already taken."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/links/{linkId}":{"parameters":[{"name":"linkId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"getLink","tags":["Links"],"summary":"Get one link.","responses":{"200":{"description":"Link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"updateLink","tags":["Links"],"summary":"Patch a link.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLinkInput"}}}},"responses":{"200":{"description":"Updated link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteLink","tags":["Links"],"summary":"Delete a link.","responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/links/{linkId}/stats":{"parameters":[{"name":"linkId","in":"path","required":true,"schema":{"type":"string"}},{"name":"period","in":"query","schema":{"type":"string","enum":["24h","7d","30d","all"]}}],"get":{"operationId":"getLinkStats","tags":["Links"],"summary":"Per-link analytics: clicks over time, geo, device, browser, referrer.","responses":{"200":{"description":"Stats payload."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/links/{linkId}/qr":{"parameters":[{"name":"linkId","in":"path","required":true,"schema":{"type":"string"}},{"name":"size","in":"query","schema":{"type":"integer","default":256}},{"name":"color","in":"query","schema":{"type":"string"}},{"name":"background","in":"query","schema":{"type":"string"}}],"get":{"operationId":"getLinkQr","tags":["Links"],"summary":"PNG QR code for a link.","responses":{"200":{"description":"PNG bytes.","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/links/bulk":{"post":{"operationId":"bulkCreateLinks","tags":["Links"],"summary":"Create many links in one request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["links"],"properties":{"links":{"type":"array","items":{"$ref":"#/components/schemas/CreateLinkInput"}}}}}}},"responses":{"200":{"description":"Bulk result with per-item success/error."},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/folders":{"get":{"operationId":"listFolders","tags":["Folders"],"summary":"List folders.","responses":{"200":{"description":"Folders.","content":{"application/json":{"schema":{"type":"object","properties":{"folders":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}}}}}}}}},"post":{"operationId":"createFolder","tags":["Folders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"color":{"type":"string"}}}}}},"responses":{"200":{"description":"Folder created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Folder"}}}}}}},"/folders/{folderId}":{"parameters":[{"name":"folderId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"operationId":"updateFolder","tags":["Folders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated."}}},"delete":{"operationId":"deleteFolder","tags":["Folders"],"responses":{"204":{"description":"Deleted."}}}},"/tags":{"get":{"operationId":"listTags","tags":["Tags"],"summary":"List tags.","responses":{"200":{"description":"Tags.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}}}}}},"post":{"operationId":"createTag","tags":["Tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"color":{"type":"string"}}}}}},"responses":{"200":{"description":"Tag created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tag"}}}},"409":{"description":"Tag with same name exists."}}}},"/analytics/overview":{"get":{"operationId":"analyticsOverview","tags":["Analytics"],"summary":"Account-wide totals + top links.","responses":{"200":{"description":"Overview payload."}}}},"/analytics/geo":{"get":{"operationId":"analyticsGeo","tags":["Analytics"],"parameters":[{"name":"period","in":"query","schema":{"type":"string","enum":["24h","7d","30d","all"]}}],"responses":{"200":{"description":"Country/city breakdown."}}}},"/conversions":{"get":{"operationId":"listConversionGoals","tags":["Conversions"],"responses":{"200":{"description":"Goals + per-goal totals.","content":{"application/json":{"schema":{"type":"object","properties":{"goals":{"type":"array","items":{"$ref":"#/components/schemas/ConversionGoal"}}}}}}}}}},"/conversions/{goalId}/track":{"parameters":[{"name":"goalId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"operationId":"trackConversion","tags":["Conversions"],"summary":"Server-side conversion event.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["linkId"],"properties":{"linkId":{"type":"string"},"revenue":{"type":"number"},"metadata":{"type":"object"}}}}}},"responses":{"201":{"description":"Event recorded."}}}},"/webhooks":{"get":{"operationId":"listWebhooks","tags":["Webhooks"],"responses":{"200":{"description":"Webhook list.","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}}}},"post":{"operationId":"createWebhook","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["create","click","expire","delete"]}}}}}}},"responses":{"200":{"description":"Webhook created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}}}}},"/domains":{"get":{"operationId":"listDomains","tags":["Domains"],"responses":{"200":{"description":"Custom domains (Pro+).","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}}}}}}}}},"tags":[{"name":"Account"},{"name":"Links"},{"name":"Folders"},{"name":"Tags"},{"name":"Analytics"},{"name":"Conversions"},{"name":"Webhooks"},{"name":"Domains"}]}