{"openapi":"3.1.2","info":{"title":"Tikio API","description":"REST API for countdown timers in email and on the web: templates, links with a stored timer, signing keys and view stats. Reference: https://tikio.io/developers.","version":"v1"},"servers":[{"url":"https://api.tikio.io"}],"tags":[{"name":"Templates","description":"Countdown designs. Read-only here — edit them in the dashboard."},{"name":"Links","description":"A link issues a countdown from a template and stores its timer."},{"name":"Timer URLs","description":"Check what a timer URL shows and why."}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key (tikio_sk_…) from Settings → API keys & AI access."}},"schemas":{}},"security":[{"apiKey":[]}],"paths":{"/v1/templates":{"get":{"tags":["Templates"],"summary":"List templates","description":"Returns your templates, newest first. Scope: tikio:read.","parameters":[{"name":"folder_id","in":"query","required":false,"schema":{"format":"uuid","description":"Only templates in this folder.","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"default":20,"description":"Page size, 1–100. Default 20.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":100,"default":20,"description":"Page size, 1–100. Default 20.","type":"integer"}]}},{"name":"starting_after","in":"query","required":false,"schema":{"format":"uuid","description":"Cursor: `next_cursor` of the previous page (the id of its last object).","type":"string"}}],"responses":{"200":{"description":"Templates, newest first.","content":{"application/json":{"schema":{"description":"Templates, newest first.","type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list","type":"string"},"data":{"type":"array","items":{"description":"A countdown design. Links are issued from a template; editing it happens in the dashboard.","examples":[{"id":"0192f7a4-3c1e-7b2a-9d4f-5e6a7b8c9d0e","object":"template","name":"Black Friday","folder_id":null,"layout":4,"langs":["en","de"],"published":true,"published_at":"2026-11-01T09:30:00Z","has_unpublished_changes":false,"version":7,"size":{"width":520,"height":132},"created_at":"2026-10-28T12:00:00Z","updated_at":"2026-11-01T09:30:00Z"}],"type":"object","required":["id","object","name","folder_id","layout","langs","published","published_at","has_unpublished_changes","version","size","created_at","updated_at"],"properties":{"id":{"format":"uuid","type":"string"},"object":{"const":"template","type":"string"},"name":{"type":"string"},"folder_id":{"nullable":true,"format":"uuid","type":["string","null"]},"layout":{"type":"string","enum":[3,4]},"langs":{"description":"Languages of the labels; the first is the default.","type":"array","items":{"type":"string"}},"published":{"description":"The design has been published. Links of an unpublished template show a placeholder.","type":"boolean"},"published_at":{"nullable":true,"format":"date-time","description":"Last publish.","type":["string","null"]},"has_unpublished_changes":{"description":"The draft differs from what recipients see.","type":"boolean"},"version":{"description":"Draft version (grows with every design edit).","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Draft version (grows with every design edit).","type":"integer"}]},"size":{"description":"Countdown size of the published design (the draft if the template was never published).","type":"object","required":["width","height"],"properties":{"width":{"description":"Width in px (the GIF is rendered at this size).","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Width in px (the GIF is rendered at this size).","type":"integer"}]},"height":{"description":"Height in px.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Height in px.","type":"integer"}]}}},"created_at":{"format":"date-time","description":"Creation time.","type":"string"},"updated_at":{"format":"date-time","description":"Last change.","type":"string"}}}},"has_more":{"description":"true — there is a next page; request it with starting_after=next_cursor.","type":"boolean"},"next_cursor":{"nullable":true,"description":"Pass as starting_after to get the next page; null on the last page.","type":["string","null"]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}}},"operationId":"getV1Templates"}},"/v1/templates/{id}":{"get":{"tags":["Templates"],"summary":"Retrieve a template","description":"Scope: tikio:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Template id.","type":"string"}}],"responses":{"200":{"description":"A countdown design. Links are issued from a template; editing it happens in the dashboard.","content":{"application/json":{"schema":{"description":"A countdown design. Links are issued from a template; editing it happens in the dashboard.","examples":[{"id":"0192f7a4-3c1e-7b2a-9d4f-5e6a7b8c9d0e","object":"template","name":"Black Friday","folder_id":null,"layout":4,"langs":["en","de"],"published":true,"published_at":"2026-11-01T09:30:00Z","has_unpublished_changes":false,"version":7,"size":{"width":520,"height":132},"created_at":"2026-10-28T12:00:00Z","updated_at":"2026-11-01T09:30:00Z"}],"type":"object","required":["id","object","name","folder_id","layout","langs","published","published_at","has_unpublished_changes","version","size","created_at","updated_at"],"properties":{"id":{"format":"uuid","type":"string"},"object":{"const":"template","type":"string"},"name":{"type":"string"},"folder_id":{"nullable":true,"format":"uuid","type":["string","null"]},"layout":{"type":"string","enum":[3,4]},"langs":{"description":"Languages of the labels; the first is the default.","type":"array","items":{"type":"string"}},"published":{"description":"The design has been published. Links of an unpublished template show a placeholder.","type":"boolean"},"published_at":{"nullable":true,"format":"date-time","description":"Last publish.","type":["string","null"]},"has_unpublished_changes":{"description":"The draft differs from what recipients see.","type":"boolean"},"version":{"description":"Draft version (grows with every design edit).","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Draft version (grows with every design edit).","type":"integer"}]},"size":{"description":"Countdown size of the published design (the draft if the template was never published).","type":"object","required":["width","height"],"properties":{"width":{"description":"Width in px (the GIF is rendered at this size).","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Width in px (the GIF is rendered at this size).","type":"integer"}]},"height":{"description":"Height in px.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Height in px.","type":"integer"}]}}},"created_at":{"format":"date-time","description":"Creation time.","type":"string"},"updated_at":{"format":"date-time","description":"Last change.","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}}},"operationId":"getV1TemplatesById"}},"/v1/links":{"get":{"tags":["Links"],"summary":"List links","description":"Newest first. Scope: tikio:read.","parameters":[{"name":"template_id","in":"query","required":false,"schema":{"format":"uuid","description":"Only links of this template.","type":"string"}},{"name":"active","in":"query","required":false,"schema":{"description":"Only switched-on (true) or switched-off (false) links.","type":"boolean"}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"default":20,"description":"Page size, 1–100. Default 20.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":100,"default":20,"description":"Page size, 1–100. Default 20.","type":"integer"}]}},{"name":"starting_after","in":"query","required":false,"schema":{"format":"uuid","description":"Cursor: `next_cursor` of the previous page (the id of its last object).","type":"string"}}],"responses":{"200":{"description":"Links, newest first.","content":{"application/json":{"schema":{"description":"Links, newest first.","type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list","type":"string"},"data":{"type":"array","items":{"description":"A link issues a countdown from a template and stores its timer.","examples":[{"id":"0192f7a4-5d2b-7c3d-8e4f-6a7b8c9d0e1f","object":"link","name":"BF newsletter","template_id":"0192f7a4-3c1e-7b2a-9d4f-5e6a7b8c9d0e","active":true,"valid_until":null,"timer":{"type":"deadline","source":"fixed","deadline":"2026-11-27T17:00:00Z","lang":null},"allow_query_override":false,"uid_sig_strict":false,"expired_action":"zeros","expired_image_url":null,"before_url":null,"after_url":null,"urls":{"gif":"https://t.tikio.io/e/0192f7a4-5d2b-7c3d-8e4f-6a7b8c9d0e1f.gif","html":"https://cdn.tikio.io/embeds/0192f7a4-5d2b-7c3d-8e4f-6a7b8c9d0e1f.html","click":null},"recipient_params":[{"name":"lang","required":false,"description":"Display language; overrides timer.lang."},{"name":"v","required":false,"description":"Cache-buster per send."}],"template_published":true,"created_at":"2026-11-01T10:00:00Z","updated_at":"2026-11-01T10:00:00Z"}],"type":"object","required":["id","object","name","template_id","active","valid_until","timer","allow_query_override","uid_sig_strict","expired_action","expired_image_url","before_url","after_url","urls","recipient_params","template_published","created_at","updated_at"],"properties":{"id":{"format":"uuid","type":"string"},"object":{"const":"link","type":"string"},"name":{"type":"string"},"template_id":{"format":"uuid","type":"string"},"active":{"description":"false — the link is switched off and shows a placeholder everywhere.","type":"boolean"},"valid_until":{"nullable":true,"format":"date-time","description":"After this moment the link shows a placeholder.","type":["string","null"]},"timer":{"description":"The stored timer. null — a legacy link: its timing comes entirely from the URL query (see URL parameters).","nullable":true,"anyOf":[{"anyOf":[{"type":"object","required":["type","source","deadline","lang"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"const":"fixed","type":"string"},"deadline":{"format":"date-time","description":"Moment the countdown reaches zero (UTC).","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","lang"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"const":"recipient","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","duration_seconds","per_recipient","lang"],"properties":{"type":{"const":"evergreen","type":"string"},"duration_seconds":{"minimum":60,"maximum":31536000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60,"maximum":31536000,"type":"integer"}]},"per_recipient":{"description":"true — counts from each recipient's first open (needs `uid`); false — from page load.","type":"boolean"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","repeat","at","on","timezone","lang"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"type":"string","enum":["day","weekdays","week"]},"at":{"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"Local reset time, HH:MM.","type":"string"},"on":{"nullable":true,"type":["string","null"],"enum":["mon","tue","wed","thu","fri","sat","sun"]},"timezone":{"description":"IANA time zone of `at`.","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","repeat","interval_seconds","anchor","lang"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"const":"interval","type":"string"},"interval_seconds":{"minimum":60,"maximum":31536000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60,"maximum":31536000,"type":"integer"}]},"anchor":{"nullable":true,"format":"date-time","description":"Phase anchor of the cycle; null — cycles start at 00:00 UTC, 1970-01-01.","type":["string","null"]},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","start","lang"],"properties":{"type":{"const":"countup","type":"string"},"source":{"const":"fixed","type":"string"},"start":{"format":"date-time","description":"Moment the count-up starts from (UTC).","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","lang"],"properties":{"type":{"const":"countup","type":"string"},"source":{"const":"recipient","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}}]},{"type":"null"}]},"allow_query_override":{"description":"true — timing parameters in the URL query (target, duration, cycle, countup, every, at, on, tz) replace the stored timer as a whole group. false — they are ignored.","type":"boolean"},"uid_sig_strict":{"description":"Accept uid only with a valid sig (see signing_key).","type":"boolean"},"expired_action":{"type":"string","enum":["zeros","hide","image"]},"expired_image_url":{"nullable":true,"type":["string","null"]},"before_url":{"nullable":true,"description":"Smart link: where a click leads while the countdown runs.","type":["string","null"]},"after_url":{"nullable":true,"description":"Smart link: where a click leads after zero.","type":["string","null"]},"urls":{"description":"Public URLs of the link. The timer is stored on the link, so they carry no timing query.","type":"object","required":["gif","html","click"],"properties":{"gif":{"description":"Short GIF URL for emails. Append recipient_params as a query.","type":"string"},"html":{"description":"Live HTML countdown for web pages (an <iframe>).","type":"string"},"click":{"nullable":true,"description":"Smart link; null while neither before_url nor after_url is set.","type":["string","null"]}}},"recipient_params":{"description":"Parameters your email service fills in per recipient (merge tags), appended to urls.gif as a query. Empty for a legacy link.","type":"array","items":{"type":"object","required":["name","required","description"],"properties":{"name":{"description":"Query parameter name: target, uid, sig, lang or v.","type":"string"},"required":{"description":"Without it the countdown shows a placeholder or falls back to a shared one.","type":"boolean"},"description":{"type":"string"}}}},"embed_code":{"description":"Only with ?include=embed_code. Ready-to-paste HTML; replace {{…}} placeholders with your email service's merge tags. null for a legacy link.","nullable":true,"type":["object","null"],"required":["email","web"],"properties":{"email":{"description":"<img> for an email, wrapped in the smart link when one is set.","type":"string"},"web":{"description":"<iframe> for a web page.","type":"string"}}},"template_published":{"description":"false — the template has never been published: the URLs show a placeholder until it is.","type":"boolean"},"created_at":{"format":"date-time","description":"Creation time.","type":"string"},"updated_at":{"format":"date-time","description":"Last change of the settings.","type":"string"}}}},"has_more":{"description":"true — there is a next page; request it with starting_after=next_cursor.","type":"boolean"},"next_cursor":{"nullable":true,"description":"Pass as starting_after to get the next page; null on the last page.","type":["string","null"]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}}},"operationId":"getV1Links"},"post":{"tags":["Links"],"summary":"Create a link","description":"Issues a link from a template with a stored timer; the answer carries the short URL (urls.gif) and the recipient parameters to append. Scope: tikio:publish.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["template_id"],"properties":{"template_id":{"format":"uuid","description":"The template to issue the link from.","type":"string"},"name":{"maxLength":200,"description":"Your label for the link.","type":"string"},"timer":{"description":"Required. The stored timer of the link. Moments: ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds. Durations: 60 s – 1 year.","examples":[{"type":"deadline","deadline":"2026-11-27T18:00:00+01:00"},{"type":"deadline","source":"recipient"},{"type":"evergreen","duration_seconds":86400,"per_recipient":true},{"type":"recurring","repeat":"day","at":"14:00","timezone":"Europe/Berlin"},{"type":"recurring","repeat":"interval","interval_seconds":5400,"anchor":null},{"type":"countup","start":"2026-01-01T00:00:00Z"}],"nullable":true,"anyOf":[{"anyOf":[{"type":"object","required":["type"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"type":"string","enum":["fixed","recipient"]},"deadline":{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type","duration_seconds"],"properties":{"type":{"const":"evergreen","type":"string"},"duration_seconds":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"per_recipient":{"type":"boolean"},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type","repeat"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"anyOf":[{"type":"string","enum":["day","weekdays","week"]},{"const":"interval","type":"string"}]},"at":{"type":"string"},"on":{"nullable":true,"type":["string","null"]},"timezone":{"type":"string"},"interval_seconds":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"anchor":{"nullable":true,"anyOf":[{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},{"type":"null"}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type"],"properties":{"type":{"const":"countup","type":"string"},"source":{"type":"string","enum":["fixed","recipient"]},"start":{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}}]},{"type":"null"}]},"allow_query_override":{"description":"Let timing parameters in the URL query replace the stored timer. Default false.","type":"boolean"},"expired_action":{"type":"string","enum":["zeros","hide","image"]},"expired_image_url":{"nullable":true,"maxLength":2048,"description":"Image shown after zero when expired_action=image. Absolute http(s) URL; null or \"\" clears it.","type":["string","null"]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["template_id"],"properties":{"template_id":{"format":"uuid","description":"The template to issue the link from.","type":"string"},"name":{"maxLength":200,"description":"Your label for the link.","type":"string"},"timer":{"description":"Required. The stored timer of the link. Moments: ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds. Durations: 60 s – 1 year.","examples":[{"type":"deadline","deadline":"2026-11-27T18:00:00+01:00"},{"type":"deadline","source":"recipient"},{"type":"evergreen","duration_seconds":86400,"per_recipient":true},{"type":"recurring","repeat":"day","at":"14:00","timezone":"Europe/Berlin"},{"type":"recurring","repeat":"interval","interval_seconds":5400,"anchor":null},{"type":"countup","start":"2026-01-01T00:00:00Z"}],"nullable":true,"anyOf":[{"anyOf":[{"type":"object","required":["type"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"type":"string","enum":["fixed","recipient"]},"deadline":{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type","duration_seconds"],"properties":{"type":{"const":"evergreen","type":"string"},"duration_seconds":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"per_recipient":{"type":"boolean"},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type","repeat"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"anyOf":[{"type":"string","enum":["day","weekdays","week"]},{"const":"interval","type":"string"}]},"at":{"type":"string"},"on":{"nullable":true,"type":["string","null"]},"timezone":{"type":"string"},"interval_seconds":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"anchor":{"nullable":true,"anyOf":[{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},{"type":"null"}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type"],"properties":{"type":{"const":"countup","type":"string"},"source":{"type":"string","enum":["fixed","recipient"]},"start":{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}}]},{"type":"null"}]},"allow_query_override":{"description":"Let timing parameters in the URL query replace the stored timer. Default false.","type":"boolean"},"expired_action":{"type":"string","enum":["zeros","hide","image"]},"expired_image_url":{"nullable":true,"maxLength":2048,"description":"Image shown after zero when expired_action=image. Absolute http(s) URL; null or \"\" clears it.","type":["string","null"]}}}},"multipart/form-data":{"schema":{"type":"object","required":["template_id"],"properties":{"template_id":{"format":"uuid","description":"The template to issue the link from.","type":"string"},"name":{"maxLength":200,"description":"Your label for the link.","type":"string"},"timer":{"description":"Required. The stored timer of the link. Moments: ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds. Durations: 60 s – 1 year.","examples":[{"type":"deadline","deadline":"2026-11-27T18:00:00+01:00"},{"type":"deadline","source":"recipient"},{"type":"evergreen","duration_seconds":86400,"per_recipient":true},{"type":"recurring","repeat":"day","at":"14:00","timezone":"Europe/Berlin"},{"type":"recurring","repeat":"interval","interval_seconds":5400,"anchor":null},{"type":"countup","start":"2026-01-01T00:00:00Z"}],"nullable":true,"anyOf":[{"anyOf":[{"type":"object","required":["type"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"type":"string","enum":["fixed","recipient"]},"deadline":{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type","duration_seconds"],"properties":{"type":{"const":"evergreen","type":"string"},"duration_seconds":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"per_recipient":{"type":"boolean"},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type","repeat"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"anyOf":[{"type":"string","enum":["day","weekdays","week"]},{"const":"interval","type":"string"}]},"at":{"type":"string"},"on":{"nullable":true,"type":["string","null"]},"timezone":{"type":"string"},"interval_seconds":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"anchor":{"nullable":true,"anyOf":[{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},{"type":"null"}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type"],"properties":{"type":{"const":"countup","type":"string"},"source":{"type":"string","enum":["fixed","recipient"]},"start":{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}}]},{"type":"null"}]},"allow_query_override":{"description":"Let timing parameters in the URL query replace the stored timer. Default false.","type":"boolean"},"expired_action":{"type":"string","enum":["zeros","hide","image"]},"expired_image_url":{"nullable":true,"maxLength":2048,"description":"Image shown after zero when expired_action=image. Absolute http(s) URL; null or \"\" clears it.","type":["string","null"]}}}}}},"responses":{"201":{"description":"A link issues a countdown from a template and stores its timer.","content":{"application/json":{"schema":{"description":"A link issues a countdown from a template and stores its timer.","examples":[{"id":"0192f7a4-5d2b-7c3d-8e4f-6a7b8c9d0e1f","object":"link","name":"BF newsletter","template_id":"0192f7a4-3c1e-7b2a-9d4f-5e6a7b8c9d0e","active":true,"valid_until":null,"timer":{"type":"deadline","source":"fixed","deadline":"2026-11-27T17:00:00Z","lang":null},"allow_query_override":false,"uid_sig_strict":false,"expired_action":"zeros","expired_image_url":null,"before_url":null,"after_url":null,"urls":{"gif":"https://t.tikio.io/e/0192f7a4-5d2b-7c3d-8e4f-6a7b8c9d0e1f.gif","html":"https://cdn.tikio.io/embeds/0192f7a4-5d2b-7c3d-8e4f-6a7b8c9d0e1f.html","click":null},"recipient_params":[{"name":"lang","required":false,"description":"Display language; overrides timer.lang."},{"name":"v","required":false,"description":"Cache-buster per send."}],"template_published":true,"created_at":"2026-11-01T10:00:00Z","updated_at":"2026-11-01T10:00:00Z"}],"type":"object","required":["id","object","name","template_id","active","valid_until","timer","allow_query_override","uid_sig_strict","expired_action","expired_image_url","before_url","after_url","urls","recipient_params","template_published","created_at","updated_at"],"properties":{"id":{"format":"uuid","type":"string"},"object":{"const":"link","type":"string"},"name":{"type":"string"},"template_id":{"format":"uuid","type":"string"},"active":{"description":"false — the link is switched off and shows a placeholder everywhere.","type":"boolean"},"valid_until":{"nullable":true,"format":"date-time","description":"After this moment the link shows a placeholder.","type":["string","null"]},"timer":{"description":"The stored timer. null — a legacy link: its timing comes entirely from the URL query (see URL parameters).","nullable":true,"anyOf":[{"anyOf":[{"type":"object","required":["type","source","deadline","lang"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"const":"fixed","type":"string"},"deadline":{"format":"date-time","description":"Moment the countdown reaches zero (UTC).","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","lang"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"const":"recipient","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","duration_seconds","per_recipient","lang"],"properties":{"type":{"const":"evergreen","type":"string"},"duration_seconds":{"minimum":60,"maximum":31536000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60,"maximum":31536000,"type":"integer"}]},"per_recipient":{"description":"true — counts from each recipient's first open (needs `uid`); false — from page load.","type":"boolean"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","repeat","at","on","timezone","lang"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"type":"string","enum":["day","weekdays","week"]},"at":{"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"Local reset time, HH:MM.","type":"string"},"on":{"nullable":true,"type":["string","null"],"enum":["mon","tue","wed","thu","fri","sat","sun"]},"timezone":{"description":"IANA time zone of `at`.","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","repeat","interval_seconds","anchor","lang"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"const":"interval","type":"string"},"interval_seconds":{"minimum":60,"maximum":31536000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60,"maximum":31536000,"type":"integer"}]},"anchor":{"nullable":true,"format":"date-time","description":"Phase anchor of the cycle; null — cycles start at 00:00 UTC, 1970-01-01.","type":["string","null"]},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","start","lang"],"properties":{"type":{"const":"countup","type":"string"},"source":{"const":"fixed","type":"string"},"start":{"format":"date-time","description":"Moment the count-up starts from (UTC).","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","lang"],"properties":{"type":{"const":"countup","type":"string"},"source":{"const":"recipient","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}}]},{"type":"null"}]},"allow_query_override":{"description":"true — timing parameters in the URL query (target, duration, cycle, countup, every, at, on, tz) replace the stored timer as a whole group. false — they are ignored.","type":"boolean"},"uid_sig_strict":{"description":"Accept uid only with a valid sig (see signing_key).","type":"boolean"},"expired_action":{"type":"string","enum":["zeros","hide","image"]},"expired_image_url":{"nullable":true,"type":["string","null"]},"before_url":{"nullable":true,"description":"Smart link: where a click leads while the countdown runs.","type":["string","null"]},"after_url":{"nullable":true,"description":"Smart link: where a click leads after zero.","type":["string","null"]},"urls":{"description":"Public URLs of the link. The timer is stored on the link, so they carry no timing query.","type":"object","required":["gif","html","click"],"properties":{"gif":{"description":"Short GIF URL for emails. Append recipient_params as a query.","type":"string"},"html":{"description":"Live HTML countdown for web pages (an <iframe>).","type":"string"},"click":{"nullable":true,"description":"Smart link; null while neither before_url nor after_url is set.","type":["string","null"]}}},"recipient_params":{"description":"Parameters your email service fills in per recipient (merge tags), appended to urls.gif as a query. Empty for a legacy link.","type":"array","items":{"type":"object","required":["name","required","description"],"properties":{"name":{"description":"Query parameter name: target, uid, sig, lang or v.","type":"string"},"required":{"description":"Without it the countdown shows a placeholder or falls back to a shared one.","type":"boolean"},"description":{"type":"string"}}}},"embed_code":{"description":"Only with ?include=embed_code. Ready-to-paste HTML; replace {{…}} placeholders with your email service's merge tags. null for a legacy link.","nullable":true,"type":["object","null"],"required":["email","web"],"properties":{"email":{"description":"<img> for an email, wrapped in the smart link when one is set.","type":"string"},"web":{"description":"<iframe> for a web page.","type":"string"}}},"template_published":{"description":"false — the template has never been published: the URLs show a placeholder until it is.","type":"boolean"},"created_at":{"format":"date-time","description":"Creation time.","type":"string"},"updated_at":{"format":"date-time","description":"Last change of the settings.","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}}},"operationId":"postV1Links"}},"/v1/links/{id}":{"get":{"tags":["Links"],"summary":"Retrieve a link","description":"Scope: tikio:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Link id.","type":"string"}},{"name":"include","in":"query","required":false,"schema":{"description":"embed_code — add ready-to-paste HTML.","const":"embed_code","type":"string"}}],"responses":{"200":{"description":"A link issues a countdown from a template and stores its timer.","content":{"application/json":{"schema":{"description":"A link issues a countdown from a template and stores its timer.","examples":[{"id":"0192f7a4-5d2b-7c3d-8e4f-6a7b8c9d0e1f","object":"link","name":"BF newsletter","template_id":"0192f7a4-3c1e-7b2a-9d4f-5e6a7b8c9d0e","active":true,"valid_until":null,"timer":{"type":"deadline","source":"fixed","deadline":"2026-11-27T17:00:00Z","lang":null},"allow_query_override":false,"uid_sig_strict":false,"expired_action":"zeros","expired_image_url":null,"before_url":null,"after_url":null,"urls":{"gif":"https://t.tikio.io/e/0192f7a4-5d2b-7c3d-8e4f-6a7b8c9d0e1f.gif","html":"https://cdn.tikio.io/embeds/0192f7a4-5d2b-7c3d-8e4f-6a7b8c9d0e1f.html","click":null},"recipient_params":[{"name":"lang","required":false,"description":"Display language; overrides timer.lang."},{"name":"v","required":false,"description":"Cache-buster per send."}],"template_published":true,"created_at":"2026-11-01T10:00:00Z","updated_at":"2026-11-01T10:00:00Z"}],"type":"object","required":["id","object","name","template_id","active","valid_until","timer","allow_query_override","uid_sig_strict","expired_action","expired_image_url","before_url","after_url","urls","recipient_params","template_published","created_at","updated_at"],"properties":{"id":{"format":"uuid","type":"string"},"object":{"const":"link","type":"string"},"name":{"type":"string"},"template_id":{"format":"uuid","type":"string"},"active":{"description":"false — the link is switched off and shows a placeholder everywhere.","type":"boolean"},"valid_until":{"nullable":true,"format":"date-time","description":"After this moment the link shows a placeholder.","type":["string","null"]},"timer":{"description":"The stored timer. null — a legacy link: its timing comes entirely from the URL query (see URL parameters).","nullable":true,"anyOf":[{"anyOf":[{"type":"object","required":["type","source","deadline","lang"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"const":"fixed","type":"string"},"deadline":{"format":"date-time","description":"Moment the countdown reaches zero (UTC).","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","lang"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"const":"recipient","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","duration_seconds","per_recipient","lang"],"properties":{"type":{"const":"evergreen","type":"string"},"duration_seconds":{"minimum":60,"maximum":31536000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60,"maximum":31536000,"type":"integer"}]},"per_recipient":{"description":"true — counts from each recipient's first open (needs `uid`); false — from page load.","type":"boolean"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","repeat","at","on","timezone","lang"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"type":"string","enum":["day","weekdays","week"]},"at":{"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"Local reset time, HH:MM.","type":"string"},"on":{"nullable":true,"type":["string","null"],"enum":["mon","tue","wed","thu","fri","sat","sun"]},"timezone":{"description":"IANA time zone of `at`.","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","repeat","interval_seconds","anchor","lang"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"const":"interval","type":"string"},"interval_seconds":{"minimum":60,"maximum":31536000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60,"maximum":31536000,"type":"integer"}]},"anchor":{"nullable":true,"format":"date-time","description":"Phase anchor of the cycle; null — cycles start at 00:00 UTC, 1970-01-01.","type":["string","null"]},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","start","lang"],"properties":{"type":{"const":"countup","type":"string"},"source":{"const":"fixed","type":"string"},"start":{"format":"date-time","description":"Moment the count-up starts from (UTC).","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","lang"],"properties":{"type":{"const":"countup","type":"string"},"source":{"const":"recipient","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}}]},{"type":"null"}]},"allow_query_override":{"description":"true — timing parameters in the URL query (target, duration, cycle, countup, every, at, on, tz) replace the stored timer as a whole group. false — they are ignored.","type":"boolean"},"uid_sig_strict":{"description":"Accept uid only with a valid sig (see signing_key).","type":"boolean"},"expired_action":{"type":"string","enum":["zeros","hide","image"]},"expired_image_url":{"nullable":true,"type":["string","null"]},"before_url":{"nullable":true,"description":"Smart link: where a click leads while the countdown runs.","type":["string","null"]},"after_url":{"nullable":true,"description":"Smart link: where a click leads after zero.","type":["string","null"]},"urls":{"description":"Public URLs of the link. The timer is stored on the link, so they carry no timing query.","type":"object","required":["gif","html","click"],"properties":{"gif":{"description":"Short GIF URL for emails. Append recipient_params as a query.","type":"string"},"html":{"description":"Live HTML countdown for web pages (an <iframe>).","type":"string"},"click":{"nullable":true,"description":"Smart link; null while neither before_url nor after_url is set.","type":["string","null"]}}},"recipient_params":{"description":"Parameters your email service fills in per recipient (merge tags), appended to urls.gif as a query. Empty for a legacy link.","type":"array","items":{"type":"object","required":["name","required","description"],"properties":{"name":{"description":"Query parameter name: target, uid, sig, lang or v.","type":"string"},"required":{"description":"Without it the countdown shows a placeholder or falls back to a shared one.","type":"boolean"},"description":{"type":"string"}}}},"embed_code":{"description":"Only with ?include=embed_code. Ready-to-paste HTML; replace {{…}} placeholders with your email service's merge tags. null for a legacy link.","nullable":true,"type":["object","null"],"required":["email","web"],"properties":{"email":{"description":"<img> for an email, wrapped in the smart link when one is set.","type":"string"},"web":{"description":"<iframe> for a web page.","type":"string"}}},"template_published":{"description":"false — the template has never been published: the URLs show a placeholder until it is.","type":"boolean"},"created_at":{"format":"date-time","description":"Creation time.","type":"string"},"updated_at":{"format":"date-time","description":"Last change of the settings.","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}}},"operationId":"getV1LinksById"},"patch":{"tags":["Links"],"summary":"Update a link","description":"Only the fields you send change. Changes reach emails already sent within minutes. Scope: tikio:publish.","parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Link id.","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"maxLength":200,"type":"string"},"active":{"description":"false switches the link off: a placeholder everywhere at once.","type":"boolean"},"valid_until":{"nullable":true,"format":"date-time","description":"After this moment the link shows a placeholder.","type":["string","null"]},"timer":{"description":"Replaces the stored timer — also in emails already sent with the short URL (within a few minutes, CDN TTL). null is rejected (timer_required): a link cannot go back to legacy. Setting the first timer on a legacy link turns allow_query_override on unless you pass it. Moments: ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds. Durations: 60 s – 1 year.","examples":[{"type":"deadline","deadline":"2026-11-27T18:00:00+01:00"},{"type":"deadline","source":"recipient"},{"type":"evergreen","duration_seconds":86400,"per_recipient":true},{"type":"recurring","repeat":"day","at":"14:00","timezone":"Europe/Berlin"},{"type":"recurring","repeat":"interval","interval_seconds":5400,"anchor":null},{"type":"countup","start":"2026-01-01T00:00:00Z"}],"nullable":true,"anyOf":[{"anyOf":[{"type":"object","required":["type"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"type":"string","enum":["fixed","recipient"]},"deadline":{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type","duration_seconds"],"properties":{"type":{"const":"evergreen","type":"string"},"duration_seconds":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"per_recipient":{"type":"boolean"},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type","repeat"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"anyOf":[{"type":"string","enum":["day","weekdays","week"]},{"const":"interval","type":"string"}]},"at":{"type":"string"},"on":{"nullable":true,"type":["string","null"]},"timezone":{"type":"string"},"interval_seconds":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"anchor":{"nullable":true,"anyOf":[{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},{"type":"null"}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type"],"properties":{"type":{"const":"countup","type":"string"},"source":{"type":"string","enum":["fixed","recipient"]},"start":{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}}]},{"type":"null"}]},"allow_query_override":{"type":"boolean"},"uid_sig_strict":{"description":"Accept uid only with a valid sig.","type":"boolean"},"expired_action":{"type":"string","enum":["zeros","hide","image"]},"expired_image_url":{"nullable":true,"maxLength":2048,"description":"Image shown after zero when expired_action=image. Absolute http(s) URL; null or \"\" clears it.","type":["string","null"]},"before_url":{"nullable":true,"maxLength":2048,"description":"Smart link target while the countdown runs. Absolute http(s) URL; null or \"\" clears it.","type":["string","null"]},"after_url":{"nullable":true,"maxLength":2048,"description":"Smart link target after zero. Absolute http(s) URL; null or \"\" clears it.","type":["string","null"]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"name":{"maxLength":200,"type":"string"},"active":{"description":"false switches the link off: a placeholder everywhere at once.","type":"boolean"},"valid_until":{"nullable":true,"format":"date-time","description":"After this moment the link shows a placeholder.","type":["string","null"]},"timer":{"description":"Replaces the stored timer — also in emails already sent with the short URL (within a few minutes, CDN TTL). null is rejected (timer_required): a link cannot go back to legacy. Setting the first timer on a legacy link turns allow_query_override on unless you pass it. Moments: ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds. Durations: 60 s – 1 year.","examples":[{"type":"deadline","deadline":"2026-11-27T18:00:00+01:00"},{"type":"deadline","source":"recipient"},{"type":"evergreen","duration_seconds":86400,"per_recipient":true},{"type":"recurring","repeat":"day","at":"14:00","timezone":"Europe/Berlin"},{"type":"recurring","repeat":"interval","interval_seconds":5400,"anchor":null},{"type":"countup","start":"2026-01-01T00:00:00Z"}],"nullable":true,"anyOf":[{"anyOf":[{"type":"object","required":["type"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"type":"string","enum":["fixed","recipient"]},"deadline":{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type","duration_seconds"],"properties":{"type":{"const":"evergreen","type":"string"},"duration_seconds":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"per_recipient":{"type":"boolean"},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type","repeat"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"anyOf":[{"type":"string","enum":["day","weekdays","week"]},{"const":"interval","type":"string"}]},"at":{"type":"string"},"on":{"nullable":true,"type":["string","null"]},"timezone":{"type":"string"},"interval_seconds":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"anchor":{"nullable":true,"anyOf":[{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},{"type":"null"}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type"],"properties":{"type":{"const":"countup","type":"string"},"source":{"type":"string","enum":["fixed","recipient"]},"start":{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}}]},{"type":"null"}]},"allow_query_override":{"type":"boolean"},"uid_sig_strict":{"description":"Accept uid only with a valid sig.","type":"boolean"},"expired_action":{"type":"string","enum":["zeros","hide","image"]},"expired_image_url":{"nullable":true,"maxLength":2048,"description":"Image shown after zero when expired_action=image. Absolute http(s) URL; null or \"\" clears it.","type":["string","null"]},"before_url":{"nullable":true,"maxLength":2048,"description":"Smart link target while the countdown runs. Absolute http(s) URL; null or \"\" clears it.","type":["string","null"]},"after_url":{"nullable":true,"maxLength":2048,"description":"Smart link target after zero. Absolute http(s) URL; null or \"\" clears it.","type":["string","null"]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"maxLength":200,"type":"string"},"active":{"description":"false switches the link off: a placeholder everywhere at once.","type":"boolean"},"valid_until":{"nullable":true,"format":"date-time","description":"After this moment the link shows a placeholder.","type":["string","null"]},"timer":{"description":"Replaces the stored timer — also in emails already sent with the short URL (within a few minutes, CDN TTL). null is rejected (timer_required): a link cannot go back to legacy. Setting the first timer on a legacy link turns allow_query_override on unless you pass it. Moments: ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds. Durations: 60 s – 1 year.","examples":[{"type":"deadline","deadline":"2026-11-27T18:00:00+01:00"},{"type":"deadline","source":"recipient"},{"type":"evergreen","duration_seconds":86400,"per_recipient":true},{"type":"recurring","repeat":"day","at":"14:00","timezone":"Europe/Berlin"},{"type":"recurring","repeat":"interval","interval_seconds":5400,"anchor":null},{"type":"countup","start":"2026-01-01T00:00:00Z"}],"nullable":true,"anyOf":[{"anyOf":[{"type":"object","required":["type"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"type":"string","enum":["fixed","recipient"]},"deadline":{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type","duration_seconds"],"properties":{"type":{"const":"evergreen","type":"string"},"duration_seconds":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"per_recipient":{"type":"boolean"},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type","repeat"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"anyOf":[{"type":"string","enum":["day","weekdays","week"]},{"const":"interval","type":"string"}]},"at":{"type":"string"},"on":{"nullable":true,"type":["string","null"]},"timezone":{"type":"string"},"interval_seconds":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"anchor":{"nullable":true,"anyOf":[{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},{"type":"null"}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}},{"type":"object","required":["type"],"properties":{"type":{"const":"countup","type":"string"},"source":{"type":"string","enum":["fixed","recipient"]},"start":{"description":"ISO-8601 with a time zone (Z or ±HH:MM) or unix seconds.","anyOf":[{"type":"string"},{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}]},"lang":{"nullable":true,"maxLength":16,"type":["string","null"]}}}]},{"type":"null"}]},"allow_query_override":{"type":"boolean"},"uid_sig_strict":{"description":"Accept uid only with a valid sig.","type":"boolean"},"expired_action":{"type":"string","enum":["zeros","hide","image"]},"expired_image_url":{"nullable":true,"maxLength":2048,"description":"Image shown after zero when expired_action=image. Absolute http(s) URL; null or \"\" clears it.","type":["string","null"]},"before_url":{"nullable":true,"maxLength":2048,"description":"Smart link target while the countdown runs. Absolute http(s) URL; null or \"\" clears it.","type":["string","null"]},"after_url":{"nullable":true,"maxLength":2048,"description":"Smart link target after zero. Absolute http(s) URL; null or \"\" clears it.","type":["string","null"]}}}}}},"responses":{"200":{"description":"A link issues a countdown from a template and stores its timer.","content":{"application/json":{"schema":{"description":"A link issues a countdown from a template and stores its timer.","examples":[{"id":"0192f7a4-5d2b-7c3d-8e4f-6a7b8c9d0e1f","object":"link","name":"BF newsletter","template_id":"0192f7a4-3c1e-7b2a-9d4f-5e6a7b8c9d0e","active":true,"valid_until":null,"timer":{"type":"deadline","source":"fixed","deadline":"2026-11-27T17:00:00Z","lang":null},"allow_query_override":false,"uid_sig_strict":false,"expired_action":"zeros","expired_image_url":null,"before_url":null,"after_url":null,"urls":{"gif":"https://t.tikio.io/e/0192f7a4-5d2b-7c3d-8e4f-6a7b8c9d0e1f.gif","html":"https://cdn.tikio.io/embeds/0192f7a4-5d2b-7c3d-8e4f-6a7b8c9d0e1f.html","click":null},"recipient_params":[{"name":"lang","required":false,"description":"Display language; overrides timer.lang."},{"name":"v","required":false,"description":"Cache-buster per send."}],"template_published":true,"created_at":"2026-11-01T10:00:00Z","updated_at":"2026-11-01T10:00:00Z"}],"type":"object","required":["id","object","name","template_id","active","valid_until","timer","allow_query_override","uid_sig_strict","expired_action","expired_image_url","before_url","after_url","urls","recipient_params","template_published","created_at","updated_at"],"properties":{"id":{"format":"uuid","type":"string"},"object":{"const":"link","type":"string"},"name":{"type":"string"},"template_id":{"format":"uuid","type":"string"},"active":{"description":"false — the link is switched off and shows a placeholder everywhere.","type":"boolean"},"valid_until":{"nullable":true,"format":"date-time","description":"After this moment the link shows a placeholder.","type":["string","null"]},"timer":{"description":"The stored timer. null — a legacy link: its timing comes entirely from the URL query (see URL parameters).","nullable":true,"anyOf":[{"anyOf":[{"type":"object","required":["type","source","deadline","lang"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"const":"fixed","type":"string"},"deadline":{"format":"date-time","description":"Moment the countdown reaches zero (UTC).","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","lang"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"const":"recipient","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","duration_seconds","per_recipient","lang"],"properties":{"type":{"const":"evergreen","type":"string"},"duration_seconds":{"minimum":60,"maximum":31536000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60,"maximum":31536000,"type":"integer"}]},"per_recipient":{"description":"true — counts from each recipient's first open (needs `uid`); false — from page load.","type":"boolean"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","repeat","at","on","timezone","lang"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"type":"string","enum":["day","weekdays","week"]},"at":{"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"Local reset time, HH:MM.","type":"string"},"on":{"nullable":true,"type":["string","null"],"enum":["mon","tue","wed","thu","fri","sat","sun"]},"timezone":{"description":"IANA time zone of `at`.","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","repeat","interval_seconds","anchor","lang"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"const":"interval","type":"string"},"interval_seconds":{"minimum":60,"maximum":31536000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60,"maximum":31536000,"type":"integer"}]},"anchor":{"nullable":true,"format":"date-time","description":"Phase anchor of the cycle; null — cycles start at 00:00 UTC, 1970-01-01.","type":["string","null"]},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","start","lang"],"properties":{"type":{"const":"countup","type":"string"},"source":{"const":"fixed","type":"string"},"start":{"format":"date-time","description":"Moment the count-up starts from (UTC).","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","lang"],"properties":{"type":{"const":"countup","type":"string"},"source":{"const":"recipient","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}}]},{"type":"null"}]},"allow_query_override":{"description":"true — timing parameters in the URL query (target, duration, cycle, countup, every, at, on, tz) replace the stored timer as a whole group. false — they are ignored.","type":"boolean"},"uid_sig_strict":{"description":"Accept uid only with a valid sig (see signing_key).","type":"boolean"},"expired_action":{"type":"string","enum":["zeros","hide","image"]},"expired_image_url":{"nullable":true,"type":["string","null"]},"before_url":{"nullable":true,"description":"Smart link: where a click leads while the countdown runs.","type":["string","null"]},"after_url":{"nullable":true,"description":"Smart link: where a click leads after zero.","type":["string","null"]},"urls":{"description":"Public URLs of the link. The timer is stored on the link, so they carry no timing query.","type":"object","required":["gif","html","click"],"properties":{"gif":{"description":"Short GIF URL for emails. Append recipient_params as a query.","type":"string"},"html":{"description":"Live HTML countdown for web pages (an <iframe>).","type":"string"},"click":{"nullable":true,"description":"Smart link; null while neither before_url nor after_url is set.","type":["string","null"]}}},"recipient_params":{"description":"Parameters your email service fills in per recipient (merge tags), appended to urls.gif as a query. Empty for a legacy link.","type":"array","items":{"type":"object","required":["name","required","description"],"properties":{"name":{"description":"Query parameter name: target, uid, sig, lang or v.","type":"string"},"required":{"description":"Without it the countdown shows a placeholder or falls back to a shared one.","type":"boolean"},"description":{"type":"string"}}}},"embed_code":{"description":"Only with ?include=embed_code. Ready-to-paste HTML; replace {{…}} placeholders with your email service's merge tags. null for a legacy link.","nullable":true,"type":["object","null"],"required":["email","web"],"properties":{"email":{"description":"<img> for an email, wrapped in the smart link when one is set.","type":"string"},"web":{"description":"<iframe> for a web page.","type":"string"}}},"template_published":{"description":"false — the template has never been published: the URLs show a placeholder until it is.","type":"boolean"},"created_at":{"format":"date-time","description":"Creation time.","type":"string"},"updated_at":{"format":"date-time","description":"Last change of the settings.","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}}},"operationId":"patchV1LinksById"},"delete":{"tags":["Links"],"summary":"Delete a link","description":"Deletes the link for good: its URLs show a placeholder in every email already sent. To pause instead, PATCH active=false. Scope: tikio:delete (API keys only).","parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Link id.","type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","object","deleted"],"properties":{"id":{"format":"uuid","type":"string"},"object":{"const":"link","type":"string"},"deleted":{"const":true,"type":"boolean"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}}},"operationId":"deleteV1LinksById"}},"/v1/links/{id}/signing_key":{"get":{"tags":["Links"],"summary":"Retrieve the signing key","description":"Per-link key for signing uid: sig = base64url(HMAC_SHA256(key, uid)). Scope: tikio:publish.","parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Link id.","type":"string"}}],"responses":{"200":{"description":"Key for signing recipient ids (uid → sig).","content":{"application/json":{"schema":{"description":"Key for signing recipient ids (uid → sig).","type":"object","required":["object","link_id","key","algorithm","example"],"properties":{"object":{"const":"signing_key","type":"string"},"link_id":{"format":"uuid","type":"string"},"key":{"description":"Per-link HMAC key. Keep it on your server — never in an email or a web page.","type":"string"},"algorithm":{"description":"sig = base64url(HMAC_SHA256(key, uid)), without padding.","type":"string"},"example":{"description":"A sample pair to test your signer against.","type":"object","required":["uid","sig"],"properties":{"uid":{"type":"string"},"sig":{"type":"string"}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}}},"operationId":"getV1LinksByIdSigning_key"}},"/v1/links/{id}/stats":{"get":{"tags":["Links"],"summary":"Retrieve link stats","description":"Scope: tikio:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Link id.","type":"string"}},{"name":"days","in":"query","required":false,"schema":{"minimum":1,"maximum":90,"default":30,"description":"Window, 1–90 days.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":90,"default":30,"description":"Window, 1–90 days.","type":"integer"}]}}],"responses":{"200":{"description":"View statistics of a link for the last N days.","content":{"application/json":{"schema":{"description":"View statistics of a link for the last N days.","type":"object","required":["object","link_id","days","total","email_views","clicks","prev","daily","policies","clients","countries","hours"],"properties":{"object":{"const":"link_stats","type":"string"},"link_id":{"format":"uuid","type":"string"},"days":{"description":"Window length in days (1–90).","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Window length in days (1–90).","type":"integer"}]},"total":{"minimum":0,"description":"Views: email opens (GIF) plus web views (HTML).","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Views: email opens (GIF) plus web views (HTML).","type":"integer"}]},"email_views":{"minimum":0,"description":"Part of total that are email opens.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Part of total that are email opens.","type":"integer"}]},"clicks":{"minimum":0,"description":"Smart-link clicks (not part of total).","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Smart-link clicks (not part of total).","type":"integer"}]},"prev":{"description":"The same counts for the preceding window of equal length.","type":"object","required":["total","email_views","clicks"],"properties":{"total":{"minimum":0,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"type":"integer"}]},"email_views":{"minimum":0,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"type":"integer"}]},"clicks":{"minimum":0,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"type":"integer"}]}}},"daily":{"type":"array","items":{"type":"object","required":["date","gif","html","static","clicks"],"properties":{"date":{"description":"YYYY-MM-DD (UTC).","type":"string"},"gif":{"minimum":0,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"type":"integer"}]},"html":{"minimum":0,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"type":"integer"}]},"static":{"minimum":0,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"type":"integer"}]},"clicks":{"minimum":0,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"type":"integer"}]}}}},"policies":{"description":"Views by display class.","type":"array","items":{"type":"object","required":["policy","views"],"properties":{"policy":{"type":"string"},"views":{"minimum":0,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"type":"integer"}]}}}},"clients":{"description":"Views by email client / browser.","type":"array","items":{"type":"object","required":["client","views"],"properties":{"client":{"nullable":true,"type":["string","null"]},"views":{"minimum":0,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"type":"integer"}]}}}},"countries":{"description":"Views by country (ISO 3166-1 alpha-2).","type":"array","items":{"type":"object","required":["country","views"],"properties":{"country":{"nullable":true,"type":["string","null"]},"views":{"minimum":0,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"type":"integer"}]}}}},"hours":{"minItems":24,"maxItems":24,"description":"Views by hour of day, UTC.","type":"array","items":{"minimum":0,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"type":"integer"}]}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}}},"operationId":"getV1LinksByIdStats"}},"/v1/timer_urls/validate":{"post":{"tags":["Timer URLs"],"summary":"Validate a timer URL","description":"Explains what a timer URL shows and why: errors and warnings with codes, which parameters were used, ignored or missing, the effective timer, the uid signature, and what the counter reads right now. Answers 200 also when valid is false. Changes nothing and is not counted as a view. Scope: tikio:read; 60 requests a minute per key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"maxLength":4096,"description":"A full timer URL as it appears in the email or page: …/e/<id>.gif?…, …/e/<id>.html?…, …/embeds/<id>.html?… or …/c/<id>?…. Merge tags may stay unfilled.","type":"string"},"link_id":{"format":"uuid","description":"Instead of url: the link to check with `params`.","type":"string"},"params":{"maxProperties":50,"description":"With link_id: the URL query as a flat object, e.g. {\"uid\": \"*|UNIQID|*\", \"v\": \"bf-2026\"}.","type":"object","patternProperties":{"^(.*)$":{"maxLength":2048,"type":"string"}}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"url":{"maxLength":4096,"description":"A full timer URL as it appears in the email or page: …/e/<id>.gif?…, …/e/<id>.html?…, …/embeds/<id>.html?… or …/c/<id>?…. Merge tags may stay unfilled.","type":"string"},"link_id":{"format":"uuid","description":"Instead of url: the link to check with `params`.","type":"string"},"params":{"maxProperties":50,"description":"With link_id: the URL query as a flat object, e.g. {\"uid\": \"*|UNIQID|*\", \"v\": \"bf-2026\"}.","type":"object","patternProperties":{"^(.*)$":{"maxLength":2048,"type":"string"}}}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"url":{"maxLength":4096,"description":"A full timer URL as it appears in the email or page: …/e/<id>.gif?…, …/e/<id>.html?…, …/embeds/<id>.html?… or …/c/<id>?…. Merge tags may stay unfilled.","type":"string"},"link_id":{"format":"uuid","description":"Instead of url: the link to check with `params`.","type":"string"},"params":{"maxProperties":50,"description":"With link_id: the URL query as a flat object, e.g. {\"uid\": \"*|UNIQID|*\", \"v\": \"bf-2026\"}.","type":"object","patternProperties":{"^(.*)$":{"maxLength":2048,"type":"string"}}}}}}}},"responses":{"200":{"description":"Result of checking a timer URL.","content":{"application/json":{"schema":{"description":"Result of checking a timer URL.","examples":[{"object":"timer_url_validation","valid":false,"link_id":"0192f7a4-5d2b-7c3d-8e4f-6a7b8c9d0e1f","url_kind":"gif","mode":"stored","errors":[{"severity":"error","code":"missing_recipient_target","param":"target","message":"The link takes the deadline from the recipient, but the URL has no target."}],"warnings":[{"severity":"warning","code":"unknown_param","param":"utm_source","message":"utm_source is not a timer parameter and is ignored."}],"params":{"accepted":{},"ignored":[{"name":"utm_source","reason":"unknown_param"}],"missing":["target"]},"effective_timer":{"type":"deadline","source":"recipient","lang":null},"effective_timer_source":"stored","uid":{"present":false,"signature":"not_required"},"shows_now":{"kind":"placeholder","reason":"no_when"}}],"type":"object","required":["object","valid","link_id","url_kind","mode","errors","warnings","params","effective_timer","effective_timer_source","uid","shows_now"],"properties":{"object":{"const":"timer_url_validation","type":"string"},"valid":{"description":"true when `errors` is empty. Warnings — an unfilled merge tag, an ignored utm_* — do not make a URL invalid.","type":"boolean"},"link_id":{"format":"uuid","type":"string"},"url_kind":{"type":"string","enum":["gif","html","static_html","click"]},"mode":{"type":"string","enum":["stored","legacy_query"]},"errors":{"description":"Problems that make the timer show wrong or nothing.","type":"array","items":{"type":"object","required":["severity","code","param","message"],"properties":{"severity":{"const":"error","type":"string"},"code":{"description":"Error code. Each one means the URL shows a placeholder or the wrong countdown.","type":"string","enum":["target_without_timezone","bad_target","target_out_of_range","bad_schedule","bad_duration","bad_interval","countup_without_start","missing_recipient_target","no_timing","link_inactive","link_expired","template_unpublished"]},"param":{"nullable":true,"description":"The URL parameter the issue is about, e.g. target; null — the link itself.","type":["string","null"]},"message":{"description":"Human-readable explanation with the fix.","type":"string"}}}},"warnings":{"description":"Worth a look, but the timer works.","type":"array","items":{"type":"object","required":["severity","code","param","message"],"properties":{"severity":{"const":"warning","type":"string"},"code":{"description":"Warning code.","type":"string","enum":["unknown_param","override_ignored","unfilled_merge_tag","uid_missing","sig_missing","sig_invalid","lang_unknown","wrong_host","deadline_in_past"]},"param":{"nullable":true,"description":"The URL parameter the issue is about, e.g. target; null — the link itself.","type":["string","null"]},"message":{"description":"Human-readable explanation with the fix.","type":"string"}}}},"params":{"description":"How the URL query was read.","type":"object","required":["accepted","ignored","missing"],"properties":{"accepted":{"description":"URL parameters that reached the display, with their values.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"ignored":{"description":"URL parameters that were dropped, with the reason.","type":"array","items":{"type":"object","required":["name","reason"],"properties":{"name":{"type":"string"},"reason":{"description":"override_not_allowed — a timing parameter on a link with allow_query_override=false; unknown_param — not a timer parameter (utm_* land here); not_per_recipient — uid on a shared evergreen.","type":"string","enum":["override_not_allowed","unknown_param","not_per_recipient"]}}}},"missing":{"description":"Parameters the link needs but the URL lacks: target, uid or sig.","type":"array","items":{"type":"string"}}}},"effective_timer":{"description":"The timer this URL shows once the stored timer and the URL are combined, in the same shape as link.timer. null — nothing readable (a legacy URL without timing, or values outside the timer model).","nullable":true,"anyOf":[{"anyOf":[{"type":"object","required":["type","source","deadline","lang"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"const":"fixed","type":"string"},"deadline":{"format":"date-time","description":"Moment the countdown reaches zero (UTC).","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","lang"],"properties":{"type":{"const":"deadline","type":"string"},"source":{"const":"recipient","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","duration_seconds","per_recipient","lang"],"properties":{"type":{"const":"evergreen","type":"string"},"duration_seconds":{"minimum":60,"maximum":31536000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60,"maximum":31536000,"type":"integer"}]},"per_recipient":{"description":"true — counts from each recipient's first open (needs `uid`); false — from page load.","type":"boolean"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","repeat","at","on","timezone","lang"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"type":"string","enum":["day","weekdays","week"]},"at":{"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"Local reset time, HH:MM.","type":"string"},"on":{"nullable":true,"type":["string","null"],"enum":["mon","tue","wed","thu","fri","sat","sun"]},"timezone":{"description":"IANA time zone of `at`.","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","repeat","interval_seconds","anchor","lang"],"properties":{"type":{"const":"recurring","type":"string"},"repeat":{"const":"interval","type":"string"},"interval_seconds":{"minimum":60,"maximum":31536000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60,"maximum":31536000,"type":"integer"}]},"anchor":{"nullable":true,"format":"date-time","description":"Phase anchor of the cycle; null — cycles start at 00:00 UTC, 1970-01-01.","type":["string","null"]},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","start","lang"],"properties":{"type":{"const":"countup","type":"string"},"source":{"const":"fixed","type":"string"},"start":{"format":"date-time","description":"Moment the count-up starts from (UTC).","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}},{"type":"object","required":["type","source","lang"],"properties":{"type":{"const":"countup","type":"string"},"source":{"const":"recipient","type":"string"},"lang":{"nullable":true,"maxLength":16,"description":"Default display language; `lang` in the URL query overrides it.","type":["string","null"]}}}]},{"type":"null"}]},"effective_timer_source":{"nullable":true,"type":["string","null"],"enum":["stored","query","stored+recipient"]},"uid":{"description":"Recipient id and its signature.","type":"object","required":["present","signature"],"properties":{"present":{"description":"The URL carries a usable uid (not empty, not an unfilled merge tag).","type":"boolean"},"signature":{"type":"string","enum":["valid","invalid","missing","not_required"]}}},"shows_now":{"description":"What the URL shows at this moment. A dry run: not counted as a view, no recipient is recorded.","anyOf":[{"description":"A countdown is shown.","type":"object","required":["kind","policy","lang","layout","digits","seconds","ended"],"properties":{"kind":{"const":"countdown","type":"string"},"policy":{"description":"Display class the URL resolves to.","type":"string","enum":["absolute","evergreen_shared","evergreen_personal","recurring","countup"]},"lang":{"description":"Language the labels are shown in.","type":"string"},"layout":{"type":"string","enum":[3,4]},"digits":{"description":"What the counter reads right now, e.g. 02:13:45:07.","type":"string"},"seconds":{"minimum":0,"description":"Seconds on the counter right now.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Seconds on the counter right now.","type":"integer"}]},"ended":{"description":"The countdown has reached zero (fixed deadline and personal evergreen).","type":"boolean"}}},{"description":"A placeholder image is shown (never an error status — a broken image in a sent email is worse).","type":"object","required":["kind","reason"],"properties":{"kind":{"const":"placeholder","type":"string"},"reason":{"description":"Why a placeholder is shown instead of a countdown.","type":"string","enum":["rate_limited","link_missing","link_off","link_expired","no_language","not_published","countup_without_start","bad_anchor","bad_schedule","no_when","hidden_after_zero","unknown"]}}},{"description":"The countdown has ended and the link swaps in its after-zero image.","type":"object","required":["kind","image_url"],"properties":{"kind":{"const":"image_after_zero","type":"string"},"image_url":{"description":"The link's expired_image_url.","type":"string"}}}]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"examples":[{"error":{"type":"invalid_request_error","code":"deadline_without_timezone","message":"timer.deadline has no time zone: add Z or an offset like +02:00 (or pass unix seconds).","param":"timer.deadline","doc_url":"https://tikio.io/developers#errors"},"request_id":"req_4f1c2a9b7e6d5c4b3a291807"}],"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","api_error"]},"code":{"description":"Machine-readable code: parameter_missing, parameter_invalid, timer_required, deadline_without_timezone, insufficient_scope, invalid_api_key, rate_limited, resource_missing, …","type":"string"},"message":{"description":"Human-readable explanation — safe to show to a developer.","type":"string"},"param":{"nullable":true,"description":"The request parameter the error is about, e.g. timer.deadline.","type":["string","null"]},"doc_url":{"type":"string"},"required_scope":{"description":"permission_error only: the scope the key lacks.","type":"string"}}},"request_id":{"description":"Same as the Tikio-Request-Id header. Quote it when contacting support.","type":"string"}}}}}}},"operationId":"postV1Timer_urlsValidate"}}}}