{"openapi":"3.1.0","info":{"title":"getlinks.si API","version":"1","description":"Create and manage getlinks.si short links with a workspace API key (`Authorization: Bearer gl_…`). Each key may make 120 requests per 60s."},"servers":[{"url":"https://api-staging.getlinks.si/v1"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Workspace API key: `Authorization: Bearer gl_…` (create one in Settings → API)."}},"schemas":{"ErrorEnvelope":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","requestId","retryable"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"ErrorCode":{"type":"string","enum":["VALIDATION_FAILED","MALFORMED_JSON","UNAUTHENTICATED","FORBIDDEN","NOT_FOUND","RATE_LIMITED","INTERNAL","INVALID_CREDENTIALS","EMAIL_REQUIRED","EMAIL_NOT_VERIFIED","ACCOUNT_LINK_CONFLICT","WORKSPACE_FORBIDDEN","SLUG_TAKEN","SLUG_RESERVED","DESTINATION_BLOCKED","LINK_NOT_FOUND","LINK_LIMIT_REACHED","PLAN_FEATURE_LOCKED","GUEST_LIMIT_REACHED","CLAIM_TOKEN_INVALID","FLOW_INVALID","STEP_TOKEN_INVALID","STEP_TOKEN_EXPIRED","TIMER_NOT_ELAPSED","CAPTCHA_FAILED","SITE_NOT_FOUND","ARTICLE_NOT_FOUND","PAYOUT_BELOW_MINIMUM","INSUFFICIENT_BALANCE","PAYOUT_METHOD_INVALID","PAYOUT_STATE_INVALID","BILLING_PROVIDER_UNAVAILABLE","WEBHOOK_SIGNATURE_INVALID","MEMBER_LIMIT_REACHED","ALREADY_MEMBER","INVITE_INVALID","INVITE_EMAIL_MISMATCH","INVITE_DAILY_LIMIT_REACHED","INVITE_COOLDOWN","API_KEY_LIMIT_REACHED"]}}},"paths":{"/workspaces/{wid}/links":{"get":{"operationId":"listLinks","summary":"List links (paginated, newest first)","security":[{"apiKey":[]}],"parameters":[{"name":"wid","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (the API key must belong to it)"},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"pageSize","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"shortUrl":{"type":"string"},"destination":{"type":"string"},"title":{"type":["string","null"]},"monetized":{"type":"boolean"},"flowProfileId":{"type":["string","null"]},"hasPassword":{"type":"boolean"},"status":{"type":"string","enum":["active","disabled","blocked","expired"]},"expiresAt":{"type":["string","null"]},"clicks":{"type":"number"},"completedViews":{"type":"number"},"earningsMicros":{"type":"number"},"createdAt":{"type":"string"}},"required":["id","slug","shortUrl","destination","title","monetized","flowProfileId","hasPassword","status","expiresAt","clicks","completedViews","earningsMicros","createdAt"],"additionalProperties":false}},"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"}},"required":["items","page","pageSize","total"],"additionalProperties":false}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key not allowed here, wrong workspace, or plan without API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited (per key and per IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"operationId":"createLink","summary":"Create a short link","security":[{"apiKey":[]}],"parameters":[{"name":"wid","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (the API key must belong to it)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"destination":{"type":"string","maxLength":2048,"format":"uri"},"slug":{"type":"string","pattern":"^[a-zA-Z0-9_-]{3,48}$"},"title":{"type":"string","maxLength":120},"monetized":{"default":true,"type":"boolean"},"flowProfileId":{"type":"string"},"password":{"type":"string","minLength":4,"maxLength":64},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["destination"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"shortUrl":{"type":"string"},"destination":{"type":"string"},"title":{"type":["string","null"]},"monetized":{"type":"boolean"},"flowProfileId":{"type":["string","null"]},"hasPassword":{"type":"boolean"},"status":{"type":"string","enum":["active","disabled","blocked","expired"]},"expiresAt":{"type":["string","null"]},"clicks":{"type":"number"},"completedViews":{"type":"number"},"earningsMicros":{"type":"number"},"createdAt":{"type":"string"}},"required":["id","slug","shortUrl","destination","title","monetized","flowProfileId","hasPassword","status","expiresAt","clicks","completedViews","earningsMicros","createdAt"],"additionalProperties":false}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key not allowed here, wrong workspace, or plan without API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited (per key and per IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/workspaces/{wid}/links/{id}":{"get":{"operationId":"getLink","summary":"Get one link","security":[{"apiKey":[]}],"parameters":[{"name":"wid","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (the API key must belong to it)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Link id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"shortUrl":{"type":"string"},"destination":{"type":"string"},"title":{"type":["string","null"]},"monetized":{"type":"boolean"},"flowProfileId":{"type":["string","null"]},"hasPassword":{"type":"boolean"},"status":{"type":"string","enum":["active","disabled","blocked","expired"]},"expiresAt":{"type":["string","null"]},"clicks":{"type":"number"},"completedViews":{"type":"number"},"earningsMicros":{"type":"number"},"createdAt":{"type":"string"}},"required":["id","slug","shortUrl","destination","title","monetized","flowProfileId","hasPassword","status","expiresAt","clicks","completedViews","earningsMicros","createdAt"],"additionalProperties":false}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key not allowed here, wrong workspace, or plan without API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited (per key and per IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"operationId":"updateLink","summary":"Update a link","security":[{"apiKey":[]}],"parameters":[{"name":"wid","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (the API key must belong to it)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Link id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"destination":{"type":"string","maxLength":2048,"format":"uri"},"title":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"monetized":{"type":"boolean"},"flowProfileId":{"type":["string","null"]},"password":{"anyOf":[{"type":"string","minLength":4,"maxLength":64},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"status":{"type":"string","enum":["active","disabled"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"shortUrl":{"type":"string"},"destination":{"type":"string"},"title":{"type":["string","null"]},"monetized":{"type":"boolean"},"flowProfileId":{"type":["string","null"]},"hasPassword":{"type":"boolean"},"status":{"type":"string","enum":["active","disabled","blocked","expired"]},"expiresAt":{"type":["string","null"]},"clicks":{"type":"number"},"completedViews":{"type":"number"},"earningsMicros":{"type":"number"},"createdAt":{"type":"string"}},"required":["id","slug","shortUrl","destination","title","monetized","flowProfileId","hasPassword","status","expiresAt","clicks","completedViews","earningsMicros","createdAt"],"additionalProperties":false}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key not allowed here, wrong workspace, or plan without API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited (per key and per IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"operationId":"deleteLink","summary":"Delete a link","security":[{"apiKey":[]}],"parameters":[{"name":"wid","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (the API key must belong to it)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Link id"}],"responses":{"204":{"description":"No content"},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key not allowed here, wrong workspace, or plan without API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited (per key and per IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/workspaces/{wid}/links/{id}/stats":{"get":{"operationId":"getLinkStats","summary":"Daily clicks, completed views and earnings for a link","security":[{"apiKey":[]}],"parameters":[{"name":"wid","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (the API key must belong to it)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Link id"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"series":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"clicks":{"type":"number"},"completedViews":{"type":"number"},"earningsMicros":{"type":"number"}},"required":["date","clicks","completedViews","earningsMicros"],"additionalProperties":false}},"countries":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"views":{"type":"number"}},"required":["country","views"],"additionalProperties":false}},"referrers":{"type":"array","items":{"type":"object","properties":{"host":{"type":"string"},"clicks":{"type":"number"}},"required":["host","clicks"],"additionalProperties":false}}},"required":["series","countries","referrers"],"additionalProperties":false}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Key not allowed here, wrong workspace, or plan without API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited (per key and per IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}