{"openapi":"3.1.0","info":{"title":"Shortify API","version":"1.0.0","summary":"Customer-facing Shortify v1 API for links, deep links, domains, analytics, and client attribution.","description":"The Shortify API creates and manages customer-owned links, reads analytics, and supports publishable-key client attribution. Webhook management, QR APIs, app management, domain mutation, raw key lifecycle, billing, admin, support, and infrastructure operations are not part of this public API."},"servers":[{"url":"https://api.shortify.com","description":"Production"}],"tags":[{"name":"Links"},{"name":"Deep Links"},{"name":"Domains"},{"name":"Analytics"},{"name":"Client"}],"paths":{"/v1/links":{"get":{"tags":["Links"],"summary":"List links","security":[{"ServerApiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum number of records to return. Values above 100 are capped."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor returned by the previous response pagination.nextCursor value."},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Search title, destination URL, short link, key, domain, or tag name."},{"name":"tag","in":"query","required":false,"schema":{"type":"string"},"description":"Exact tag-name filter."},{"name":"domain","in":"query","required":false,"schema":{"type":"string"},"description":"Exact domain filter."},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["created_at_desc","created_at_asc","updated_at_desc","updated_at_asc","clicks_desc","clicks_asc"],"default":"created_at_desc"}}],"responses":{"200":{"description":"Paginated response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Link"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["Links"],"summary":"Create link","security":[{"ServerApiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Optional key for replay-safe create requests. The same key must use the same request body for 24 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkCreateRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Link"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/links/{linkId}":{"get":{"tags":["Links"],"summary":"Retrieve link","security":[{"ServerApiKey":[]}],"parameters":[{"name":"linkId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Link"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"tags":["Links"],"summary":"Update link","security":[{"ServerApiKey":[]}],"parameters":[{"name":"linkId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkPatchRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Link"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"tags":["Links"],"summary":"Archive link","security":[{"ServerApiKey":[]}],"parameters":[{"name":"linkId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Link"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/deep-links":{"get":{"tags":["Deep Links"],"summary":"List deep links","security":[{"ServerApiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum number of records to return. Values above 100 are capped."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor returned by the previous response pagination.nextCursor value."},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Search title, destination URL, short link, key, domain, or tag name."},{"name":"tag","in":"query","required":false,"schema":{"type":"string"},"description":"Exact tag-name filter."},{"name":"domain","in":"query","required":false,"schema":{"type":"string"},"description":"Exact domain filter."},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["created_at_desc","created_at_asc","updated_at_desc","updated_at_asc","clicks_desc","clicks_asc"],"default":"created_at_desc"}}],"responses":{"200":{"description":"Paginated response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Link"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["Deep Links"],"summary":"Create deep link","security":[{"ServerApiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Optional key for replay-safe create requests. The same key must use the same request body for 24 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeepLinkCreateRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Link"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/deep-links/{linkId}":{"get":{"tags":["Deep Links"],"summary":"Retrieve deep link","security":[{"ServerApiKey":[]}],"parameters":[{"name":"linkId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Link"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"tags":["Deep Links"],"summary":"Update deep link","security":[{"ServerApiKey":[]}],"parameters":[{"name":"linkId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkPatchRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Link"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"tags":["Deep Links"],"summary":"Archive deep link","security":[{"ServerApiKey":[]}],"parameters":[{"name":"linkId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Link"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/domains":{"get":{"tags":["Domains"],"summary":"List domains","security":[{"ServerApiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum number of records to return. Values above 100 are capped."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor returned by the previous response pagination.nextCursor value."},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"domain","in":"query","required":false,"schema":{"type":"string"}},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["created_at_desc","created_at_asc","updated_at_desc","updated_at_asc"],"default":"created_at_desc"}}],"responses":{"200":{"description":"Paginated response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/domains/{domainId}":{"get":{"tags":["Domains"],"summary":"Retrieve domain","security":[{"ServerApiKey":[]}],"parameters":[{"name":"domainId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Domain"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/analytics/links/{linkId}":{"get":{"tags":["Analytics"],"summary":"Get link analytics","security":[{"ServerApiKey":[]}],"parameters":[{"name":"linkId","in":"path","required":true,"schema":{"type":"string"}},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d","90d"],"default":"7d"}},{"name":"traffic","in":"query","required":false,"schema":{"type":"string","enum":["human","all","bots"],"default":"human"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnalyticsData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/AnalyticsUnavailable"}}}},"/v1/analytics/deep-link-app":{"get":{"tags":["Analytics"],"summary":"Get deep-link app analytics","security":[{"AppApiKey":[]}],"parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d","90d"],"default":"7d"}},{"name":"traffic","in":"query","required":false,"schema":{"type":"string","enum":["human","all","bots"],"default":"human"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeepLinkAppAnalyticsData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/AnalyticsUnavailable"}}}},"/v1/analytics/events":{"get":{"tags":["Analytics"],"summary":"Export raw analytics events","security":[{"ServerApiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum number of records to return. Values above 100 are capped."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor returned by the previous response pagination.nextCursor value."},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d","90d"],"default":"7d"}},{"name":"eventType","in":"query","required":false,"schema":{"type":"string","enum":["all","click","launch_view_impression","launch_view_auto_open_attempt","launch_view_primary_click","launch_view_secondary_click","install","first_open","customer_event"],"default":"all"}}],"responses":{"200":{"description":"Paginated response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RawAnalyticsEvent"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/AnalyticsUnavailable"}}}},"/v1/client/resolve":{"post":{"tags":["Client"],"summary":"Resolve a client link","security":[{"PublishableClientKey":[]},{"PublishableBearerKey":[]}],"parameters":[{"name":"x-publishable-key","in":"header","required":false,"schema":{"type":"string"},"description":"Publishable client key. Authorization: Bearer and publishable-key are also accepted."},{"name":"x-shortify-environment","in":"header","required":false,"schema":{"type":"string"},"description":"Optional environment scope. Must match the publishable key when provided."},{"name":"x-shortify-platform","in":"header","required":false,"schema":{"type":"string","enum":["browser","android","ios"]},"description":"Optional platform scope. Must match the publishable key when provided."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientLinkReference"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ClientResolveResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/client/attribution/click":{"post":{"tags":["Client"],"summary":"Record a client click","security":[{"PublishableClientKey":[]},{"PublishableBearerKey":[]}],"parameters":[{"name":"x-publishable-key","in":"header","required":false,"schema":{"type":"string"},"description":"Publishable client key. Authorization: Bearer and publishable-key are also accepted."},{"name":"x-shortify-environment","in":"header","required":false,"schema":{"type":"string"},"description":"Optional environment scope. Must match the publishable key when provided."},{"name":"x-shortify-platform","in":"header","required":false,"schema":{"type":"string","enum":["browser","android","ios"]},"description":"Optional platform scope. Must match the publishable key when provided."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientLinkReference"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ClientClickResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/client/deferred-deep-link":{"post":{"tags":["Client"],"summary":"Look up a deferred deep link","security":[{"PublishableClientKey":[]},{"PublishableBearerKey":[]}],"parameters":[{"name":"x-publishable-key","in":"header","required":false,"schema":{"type":"string"},"description":"Publishable client key. Authorization: Bearer and publishable-key are also accepted."},{"name":"x-shortify-environment","in":"header","required":false,"schema":{"type":"string"},"description":"Optional environment scope. Must match the publishable key when provided."},{"name":"x-shortify-platform","in":"header","required":false,"schema":{"type":"string","enum":["browser","android","ios"]},"description":"Optional platform scope. Must match the publishable key when provided."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirstOpenRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeferredDeepLinkResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/client/first-open":{"post":{"tags":["Client"],"summary":"Record first open or install","security":[{"PublishableClientKey":[]},{"PublishableBearerKey":[]}],"parameters":[{"name":"x-publishable-key","in":"header","required":false,"schema":{"type":"string"},"description":"Publishable client key. Authorization: Bearer and publishable-key are also accepted."},{"name":"x-shortify-environment","in":"header","required":false,"schema":{"type":"string"},"description":"Optional environment scope. Must match the publishable key when provided."},{"name":"x-shortify-platform","in":"header","required":false,"schema":{"type":"string","enum":["browser","android","ios"]},"description":"Optional platform scope. Must match the publishable key when provided."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirstOpenRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FirstOpenResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/client/events":{"post":{"tags":["Client"],"summary":"Publish customer events","security":[{"PublishableClientKey":[]},{"PublishableBearerKey":[]}],"parameters":[{"name":"x-publishable-key","in":"header","required":false,"schema":{"type":"string"},"description":"Publishable client key. Authorization: Bearer and publishable-key are also accepted."},{"name":"x-shortify-environment","in":"header","required":false,"schema":{"type":"string"},"description":"Optional environment scope. Must match the publishable key when provided."},{"name":"x-shortify-platform","in":"header","required":false,"schema":{"type":"string","enum":["browser","android","ios"]},"description":"Optional platform scope. Must match the publishable key when provided."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerEventsRequest"}}}},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerEventsResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"ServerApiKey":{"type":"apiKey","in":"header","name":"api-key","description":"Workspace server API key. Keep this key on your server."},"AppApiKey":{"type":"apiKey","in":"header","name":"api-key","description":"Deep-link App API Key. Used for app-scoped analytics."},"PublishableClientKey":{"type":"apiKey","in":"header","name":"x-publishable-key","description":"Publishable client key for SDK and client-side attribution endpoints."},"PublishableBearerKey":{"type":"http","scheme":"bearer","description":"Publishable client key sent as Authorization: Bearer."}},"schemas":{"SuccessResponse":{"type":"object","required":["success","requestId"],"properties":{"success":{"type":"boolean","const":true},"data":{},"pagination":{"$ref":"#/components/schemas/Pagination"},"requestId":{"type":"string","format":"uuid"}}},"ErrorResponse":{"type":"object","required":["success","error","requestId"],"properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}},"requestId":{"type":"string"}}},"Pagination":{"type":"object","required":["limit","nextCursor","hasMore"],"properties":{"limit":{"type":"integer","example":25},"nextCursor":{"type":["string","null"],"example":"eyJvZmZzZXQiOjI1fQ"},"hasMore":{"type":"boolean"}}},"Tag":{"type":"object","required":["id","name","color"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"}}},"Tracking":{"type":["object","null"],"additionalProperties":true,"properties":{"utmSource":{"type":["string","null"]},"utmMedium":{"type":["string","null"]},"utmCampaign":{"type":["string","null"]},"utmTerm":{"type":["string","null"]},"utmContent":{"type":["string","null"]},"ref":{"type":["string","null"]},"campaignId":{"type":["string","null"]},"campaignName":{"type":["string","null"]},"channel":{"type":["string","null"]},"customParams":{"type":["object","null"],"additionalProperties":{"type":"string"}}}},"Link":{"type":"object","required":["id","title","url","domain","key","shortLink","passwordProtected","clicks","botClicks","createdAt","updatedAt","linkType","archived"],"properties":{"id":{"type":"string","example":"link_01"},"title":{"type":"string","example":"Pricing campaign"},"url":{"type":"string","format":"uri","example":"https://example.com/pricing"},"desktopOverrideUrl":{"type":["string","null"],"format":"uri"},"androidOverrideUrl":{"type":["string","null"],"format":"uri"},"iosOverrideUrl":{"type":["string","null"],"format":"uri"},"domain":{"type":"string","example":"go.example.com"},"key":{"type":"string","example":"pricing-2026"},"shortLink":{"type":"string","format":"uri","example":"https://go.example.com/pricing-2026"},"expiresAt":{"type":["string","null"],"format":"date-time"},"expiredUrl":{"type":["string","null"],"format":"uri"},"passwordProtected":{"type":"boolean"},"clicks":{"type":"integer"},"botClicks":{"type":"integer"},"lastClicked":{"type":["string","null"],"format":"date-time"},"lastBotClickedAt":{"type":["string","null"],"format":"date-time"},"comments":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"linkType":{"type":"string","enum":["SHORTLINK","DEEPLINK"]},"archived":{"type":"boolean"},"deepLinkAppId":{"type":["string","null"]},"objects":{"type":["object","null"],"additionalProperties":true},"tags":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}},"tracking":{"$ref":"#/components/schemas/Tracking"},"socialPreview":{}}},"LinkCreateRequest":{"type":"object","required":["url","domain"],"properties":{"url":{"type":"string","format":"uri"},"destinationUrl":{"type":"string","format":"uri","description":"Alias for url."},"domain":{"type":"string"},"key":{"type":"string","description":"Custom slug. slug is also accepted."},"slug":{"type":"string","description":"Alias for key."},"title":{"type":"string"},"objects":{"type":["object","null"],"additionalProperties":true},"tags":{"type":"array","items":{"type":"string"}},"comments":{"type":["string","null"]},"password":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"format":"date-time"},"expiredUrl":{"type":["string","null"],"format":"uri"},"tracking":{"$ref":"#/components/schemas/Tracking"},"desktopOverrideUrl":{"type":["string","null"],"format":"uri"},"androidOverrideUrl":{"type":["string","null"],"format":"uri"},"iosOverrideUrl":{"type":["string","null"],"format":"uri"},"platformOverrides":{"$ref":"#/components/schemas/PlatformOverrides"},"socialPreview":{"$ref":"#/components/schemas/SocialPreview"}}},"DeepLinkCreateRequest":{"type":"object","anyOf":[{"required":["deepLinkAppId"]},{"required":["appId"]}],"properties":{"deepLinkAppId":{"type":"string"},"appId":{"type":"string","description":"Alias for deepLinkAppId."},"url":{"type":"string","format":"uri","description":"Destination URL. Defaults to the app default URL when omitted."},"destinationUrl":{"type":"string","format":"uri","description":"Alias for url."},"key":{"type":"string","description":"Custom slug. slug is also accepted."},"slug":{"type":"string","description":"Alias for key."},"title":{"type":"string"},"objects":{"type":["object","null"],"additionalProperties":true},"tags":{"type":"array","items":{"type":"string"}},"comments":{"type":["string","null"]},"password":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"format":"date-time"},"expiredUrl":{"type":["string","null"],"format":"uri"},"tracking":{"$ref":"#/components/schemas/Tracking"},"desktopOverrideUrl":{"type":["string","null"],"format":"uri"},"androidOverrideUrl":{"type":["string","null"],"format":"uri"},"iosOverrideUrl":{"type":["string","null"],"format":"uri"},"platformOverrides":{"$ref":"#/components/schemas/PlatformOverrides"},"socialPreview":{"$ref":"#/components/schemas/SocialPreview"}}},"LinkPatchRequest":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","format":"uri"},"destinationUrl":{"type":"string","format":"uri"},"domain":{"type":"string"},"key":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"objects":{"type":["object","null"],"additionalProperties":true},"tags":{"type":"array","items":{"type":"string"}},"comments":{"type":["string","null"]},"password":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"format":"date-time"},"expiredUrl":{"type":["string","null"],"format":"uri"},"tracking":{"$ref":"#/components/schemas/Tracking"},"desktopOverrideUrl":{"type":["string","null"],"format":"uri"},"androidOverrideUrl":{"type":["string","null"],"format":"uri"},"iosOverrideUrl":{"type":["string","null"],"format":"uri"},"platformOverrides":{"$ref":"#/components/schemas/PlatformOverrides"},"socialPreview":{"$ref":"#/components/schemas/SocialPreview"}}},"PlatformOverrides":{"type":"object","properties":{"desktop":{"type":["string","null"],"format":"uri"},"android":{"type":["string","null"],"format":"uri"},"ios":{"type":["string","null"],"format":"uri"},"desktopOverrideUrl":{"type":["string","null"],"format":"uri"},"androidOverrideUrl":{"type":["string","null"],"format":"uri"},"iosOverrideUrl":{"type":["string","null"],"format":"uri"}}},"SocialPreview":{"type":["object","null"],"additionalProperties":true},"Domain":{"type":"object","required":["id","domain","verified","primary","archived","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"domain":{"type":"string","example":"go.example.com"},"verified":{"type":"boolean"},"placeholder":{"type":["string","null"]},"expiredUrl":{"type":["string","null"],"format":"uri"},"notFoundUrl":{"type":["string","null"],"format":"uri"},"primary":{"type":"boolean"},"archived":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"AnalyticsData":{"type":"object","required":["summary","timeseries","recentEvents","launchViewMetrics"],"additionalProperties":true,"properties":{"summary":{"$ref":"#/components/schemas/AnalyticsSummary"},"customerEvents":{"type":"array","items":{"$ref":"#/components/schemas/BreakdownRow"}},"timeseries":{"type":"array","items":{"$ref":"#/components/schemas/TimeseriesPoint"}},"deviceBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/BreakdownRow"}},"browserBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/BreakdownRow"}},"osBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/BreakdownRow"}},"geoBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/BreakdownRow"}},"referrerBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/BreakdownRow"}},"campaignBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/BreakdownRow"}},"destinationBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/BreakdownRow"}},"recentEvents":{"type":"array","items":{"$ref":"#/components/schemas/RecentAnalyticsEvent"}},"launchViewMetrics":{"$ref":"#/components/schemas/LaunchViewMetrics"}}},"DeepLinkAppAnalyticsData":{"allOf":[{"$ref":"#/components/schemas/AnalyticsData"},{"type":"object","properties":{"topLinks":{"type":"array","items":{"$ref":"#/components/schemas/TopDeepLink"}}}}]},"AnalyticsSummary":{"type":"object","properties":{"humanClicks":{"type":"integer"},"uniqueVisitors":{"type":"integer"},"botClicks":{"type":"integer"},"totalClicks":{"type":"integer"},"lastActivityAt":{"type":["string","null"],"format":"date-time"},"launchViewImpressions":{"type":"integer"},"launchViewAutoOpenAttempts":{"type":"integer"},"launchViewPrimaryClicks":{"type":"integer"},"launchViewSecondaryClicks":{"type":"integer"}}},"TimeseriesPoint":{"type":"object","additionalProperties":true,"properties":{"bucketStart":{"type":"string","format":"date-time"},"label":{"type":"string"},"humanClicks":{"type":"integer"},"botClicks":{"type":"integer"},"totalClicks":{"type":"integer"},"uniqueVisitors":{"type":"integer"}}},"BreakdownRow":{"type":"object","required":["key","label","count","percentage"],"additionalProperties":true,"properties":{"key":{"type":"string"},"label":{"type":"string"},"count":{"type":"integer"},"percentage":{"type":"number"}}},"RecentAnalyticsEvent":{"type":"object","additionalProperties":true,"properties":{"eventId":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"},"eventType":{"type":"string"},"responseKind":{"type":"string"},"isBot":{"type":"boolean"},"country":{"type":"string"},"deviceType":{"type":"string"},"platform":{"type":"string"},"sdkEventName":{"type":"string"}}},"LaunchViewMetrics":{"type":"object","properties":{"impressions":{"type":"integer"},"autoOpenAttempts":{"type":"integer"},"primaryClicks":{"type":"integer"},"secondaryClicks":{"type":"integer"}}},"TopDeepLink":{"type":"object","properties":{"linkId":{"type":"string"},"domain":{"type":"string"},"linkKey":{"type":"string"},"shortLink":{"type":"string","format":"uri"},"humanClicks":{"type":"integer"},"uniqueVisitors":{"type":"integer"},"launchViewImpressions":{"type":"integer"},"lastActivityAt":{"type":["string","null"],"format":"date-time"}}},"RawAnalyticsEvent":{"type":"object","additionalProperties":true,"properties":{"timestamp":{"type":"string","format":"date-time"},"eventType":{"type":"string"},"trafficType":{"type":"string","enum":["human","bot"]},"country":{"type":"string"},"deviceType":{"type":"string"},"platform":{"type":"string"},"referrerHost":{"type":"string"},"resolvedDestinationUrl":{"type":"string"},"sdkEventName":{"type":"string"},"sessionId":{"type":"string"},"clickId":{"type":"string"},"attributionId":{"type":"string"},"installId":{"type":"string"}}},"ClientLinkReference":{"type":"object","properties":{"linkId":{"type":"string"},"shortLink":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri","description":"Alias for shortLink."},"domain":{"type":"string"},"key":{"type":"string"},"slug":{"type":"string","description":"Alias for key."}}},"ClientLinkPayload":{"type":["object","null"],"properties":{"linkId":{"type":"string"},"linkType":{"type":"string","enum":["SHORTLINK","DEEPLINK"]},"deepLinkAppId":{"type":["string","null"]},"shortLink":{"type":"string","format":"uri"},"domain":{"type":"string"},"key":{"type":"string"},"url":{"type":"string","format":"uri"}}},"ClientResolveResponse":{"type":"object","properties":{"link":{"$ref":"#/components/schemas/ClientLinkPayload"}}},"ClientClickResponse":{"type":"object","properties":{"clickId":{"type":"string","format":"uuid"},"attributionId":{"type":"string","format":"uuid"},"sessionId":{"type":"string"},"installId":{"type":["string","null"]},"expiresAt":{"type":"string","format":"date-time"},"eligible":{"type":"boolean"},"deferredDeepLink":{"$ref":"#/components/schemas/ClientLinkPayload"}}},"DeferredDeepLinkResponse":{"type":"object","properties":{"matched":{"type":"boolean"},"deferredDeepLink":{"$ref":"#/components/schemas/ClientLinkPayload"}}},"FirstOpenRequest":{"allOf":[{"$ref":"#/components/schemas/ClientLinkReference"},{"type":"object","properties":{"eventType":{"type":"string","enum":["first_open","install"],"default":"first_open"},"attributionId":{"type":"string"},"clickId":{"type":"string"},"installId":{"type":"string"},"sessionId":{"type":"string"},"deviceId":{"type":"string"},"anonymousDeviceId":{"type":"string"},"externalUserId":{"type":"string","description":"Opaque non-PII user identifier."}}}]},"FirstOpenResponse":{"type":"object","properties":{"openId":{"type":"string","format":"uuid"},"matched":{"type":"boolean"},"deferredDeepLink":{"$ref":"#/components/schemas/ClientLinkPayload"}}},"CustomerEventsRequest":{"type":"object","required":["events"],"properties":{"events":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/CustomerEvent"}}}},"CustomerEvent":{"type":"object","required":["name"],"properties":{"name":{"type":"string","pattern":"^[a-zA-Z][a-zA-Z0-9_.:-]{0,63}$"},"eventId":{"type":"string"},"linkId":{"type":"string"},"clickId":{"type":"string"},"attributionId":{"type":"string"},"sessionId":{"type":"string"},"installId":{"type":"string"},"externalUserId":{"type":"string","description":"Opaque non-PII user identifier."},"properties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"maxProperties":50}}},"CustomerEventsResponse":{"type":"object","properties":{"accepted":{"type":"array","items":{"type":"object","properties":{"eventId":{"type":"string"},"status":{"type":"string","enum":["queued","duplicate"]}}}}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Credential scope does not allow this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource was not found or is not visible to the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"Conflict, such as duplicate short link or reused idempotency key with a different body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnsupportedMediaType":{"description":"Request body must be application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"AnalyticsUnavailable":{"description":"Analytics is not configured or is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}