{"openapi":"3.1.0","info":{"title":"URX API","version":"1.0.0","description":"Smart links, analytics, conversion events and webhooks. See https://urx.si/docs#api."},"servers":[{"url":"https://urx.si/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key (urx_live_…). Scopes: revenue:read, projects:read, projects:write, links:read, links:write, analytics:read, google:read, preferences:write, analytics:manage, events:write, webhooks:manage, domains:manage, workspace:read, workspace:write, members:manage, workspace:delete."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"},"requestId":{"type":"string"}}}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"perPage":{"type":"integer"},"total":{"type":"integer"},"pages":{"type":"integer"}}},"CursorPagination":{"type":"object","properties":{"limit":{"type":"integer"},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null on the last page."}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"enum":["link.created","link.updated","link.deleted","domain.verified","domain.failed","conversion.created","usage.warning"]}},"enabled":{"type":"boolean"},"disabledReason":{"type":["string","null"]},"consecutiveFailures":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Destination":{"type":"object","required":["id","kind"],"properties":{"id":{"type":"string"},"kind":{"enum":["app-store","google-play","app-gallery","galaxy-store","microsoft-store","web","deep-link","custom"]},"url":{"type":"string"},"label":{"type":"string"},"fromProject":{"enum":["ios","android","web"]}}},"Condition":{"type":"object","required":["field","op"],"properties":{"field":{"enum":["device","os","browser","in_app","country","region","language","referrer","source","utm_source","utm_medium","utm_campaign","query","time"]},"op":{"enum":["is","is_not","contains","starts_with","exists","not_exists","before","after"]},"values":{"type":"array","items":{"type":"string"}},"key":{"type":"string"}}},"Rule":{"type":"object","required":["id","conditions","destinationId"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"type":"boolean","default":true},"match":{"enum":["all","any"],"default":"all"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/Condition"}},"destinationId":{"type":"string"}}},"LinkConfig":{"type":"object","required":["destinations","defaults"],"properties":{"destinations":{"type":"array","items":{"$ref":"#/components/schemas/Destination"}},"defaults":{"type":"object","properties":{"ios":{"type":"string"},"android":{"type":"string"},"desktop":{"type":"string"},"fallback":{"type":"string"}}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/Rule"}},"params":{"type":"object","properties":{"forward":{"enum":["none","utm","all","allowlist"]},"allow":{"type":"array","items":{"type":"string"}},"drop":{"type":"array","items":{"type":"string"}},"append":{"type":"object"},"overrideExisting":{"type":"boolean"}}},"subpaths":{"type":"boolean"},"fallbackPage":{"type":"boolean"},"expiredDestinationId":{"type":"string"},"social":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"}}},"clickToken":{"type":"boolean"},"split":{"type":"object","description":"A/B split test (Pro): visitors routed to `control` are divided between 2–4 destination ids by weight (percent, adding up to 100). Returning visitors keep their variant.","required":["control","variants","startedAt"],"properties":{"control":{"type":"string"},"variants":{"type":"array","minItems":2,"maxItems":4,"items":{"type":"object","required":["id","weight"],"properties":{"id":{"type":"string"},"weight":{"type":"integer","minimum":0,"maximum":100}}}},"startedAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"}}}}},"Link":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"hostname":{"type":"string"},"slug":{"type":"string"},"name":{"type":["string","null"]},"status":{"enum":["active","paused","archived","blocked"]},"projectId":{"type":["string","null"]},"domainId":{"type":["string","null"]},"campaign":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"config":{"$ref":"#/components/schemas/LinkConfig"},"startsAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"qr":{"type":"object","properties":{"svg":{"type":"string"},"png":{"type":"string"}}},"clicks30d":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"LinkInput":{"type":"object","description":"Send `config`, or the shorthand `ios` / `android` / `web` / `fallback` URLs.","properties":{"slug":{"type":"string","description":"Omit for a random slug. Up to 3 segments: brand/campaign."},"domainId":{"type":["string","null"]},"projectId":{"type":["string","null"]},"name":{"type":"string"},"ios":{"type":"string"},"android":{"type":"string"},"web":{"type":"string"},"fallback":{"type":"string"},"config":{"$ref":"#/components/schemas/LinkConfig"},"campaign":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"startsAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"status":{"enum":["active","paused","archived"],"description":"PATCH only"}}},"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"websiteUrl":{"type":"string"},"iosAppStoreUrl":{"type":"string"},"iosBundleId":{"type":"string"},"iosTeamId":{"type":"string"},"androidPlayUrl":{"type":"string"},"androidPackage":{"type":"string"},"androidSha256":{"type":"array","items":{"type":"string"}}}},"ConversionInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string","pattern":"^[a-z0-9_.:-]{1,64}$","examples":["app_open","signup","purchase"]},"clickId":{"type":"string","description":"The urx_click parameter from the landing URL"},"linkId":{"type":"string","format":"uuid"},"externalId":{"type":"string"},"idempotencyKey":{"type":"string"},"value":{"type":"number"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"occurredAt":{"type":"string","format":"date-time"},"metadata":{"type":"object"},"kind":{"enum":["lead","sale"],"description":"lead: identifies a Contact (needs contact). sale: money paid (needs value and currency)."},"contact":{"type":"object","required":["externalId"],"description":"The person, by your own user id. A lead creates or updates them; other events are credited to an existing one.","properties":{"externalId":{"type":"string","maxLength":200},"name":{"type":"string"},"email":{"type":"string","format":"email"}}}}},"WebhookInput":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string"},"description":{"type":"string"},"events":{"type":"array","items":{"enum":["link.created","link.updated","link.deleted","domain.verified","domain.failed","conversion.created","usage.warning"]}}}}}},"paths":{"/links":{"get":{"summary":"List links","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"projectId","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"campaign","in":"query","schema":{"type":"string"}},{"name":"domainId","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"string"}},{"name":"perPage","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Links","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Link"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a link","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Link"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Slug taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/links/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a link","responses":{"200":{"description":"Link","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Link"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a link","description":"Only the fields you send change. ios, android, web and fallback update just those platforms; rules, extra destinations and UTMs stay.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkInput"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Link"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a link","responses":{"204":{"description":"Deleted"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects":{"get":{"summary":"List projects (oldest first)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"`pagination.nextCursor` from the previous page","schema":{"type":"string"}}],"responses":{"200":{"description":"Projects","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a project","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"responses":{"201":{"description":"Created"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a project","responses":{"200":{"description":"Project"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a project","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"responses":{"200":{"description":"Updated"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains":{"get":{"summary":"List custom domains","responses":{"200":{"description":"Domains"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analytics":{"get":{"summary":"Totals, series and breakdowns","parameters":[{"name":"range","in":"query","schema":{"enum":["24h","7d","30d","90d","custom"]}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"linkId","in":"query","schema":{"type":"string"}},{"name":"projectId","in":"query","schema":{"type":"string"}},{"name":"campaign","in":"query","schema":{"type":"string"}},{"name":"bots","in":"query","schema":{"enum":["0","1"]}},{"name":"groupBy","in":"query","schema":{"enum":["day","country","region","city","device","os","browser","referrer","source","utm_source","utm_medium","utm_campaign","destination","rule","domain"]}}],"responses":{"200":{"description":"Analytics"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"post":{"summary":"Record a conversion event","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionInput"}}}},"responses":{"200":{"description":"Duplicate (same idempotencyKey)"},"201":{"description":"Recorded"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"summary":"List webhook endpoints (newest first)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"`pagination.nextCursor` from the previous page","schema":{"type":"string"}}],"responses":{"200":{"description":"Endpoints","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a webhook endpoint (returns the signing secret once)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInput"}}}},"responses":{"201":{"description":"Created"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"summary":"Delete a webhook endpoint","responses":{"204":{"description":"Deleted"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not included in the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}