{"openapi":"3.0.3","info":{"title":"SimpURL API","version":"1.2.0","description":"Every public API operation requires an active Pro personal account or a Teams workspace-owner API key. The limit is 100 requests per UTC clock hour shared across all external API keys for the account or Teams workspace, not 100 per key. It resets at the next UTC hour boundary. Additional burst protections allow at most 30 writes and 15 analytics requests per minute. Authorized calls count even when validation, a resource error or burst protection rejects them; invalid credentials, missing scopes, unknown routes, OPTIONS and the public schema do not consume the allowance. Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds); a rate_limited 429 includes the actual Retry-After seconds until retrying is possible. Dashboard, extension and MCP traffic are unaffected. Link and campaign analytics omit raw IP addresses, referrers, and user agents and cap event collection at 20,000 newest rows; Page analytics has no 20,000-row cap. Pages are available to the Pro personal account or Teams workspace owner represented by the key; Profile APIs are personal-only. Keys do not authorize billing, membership, credential management, or MCP. See https://simpurl.click/help/api-keys."},"servers":[{"url":"https://go.simpurl.click/api/v1"}],"security":[{"ApiKey":[]}],"tags":[{"name":"Account","description":"Plan and quota context."},{"name":"Links","description":"Short links and link organization."},{"name":"Campaigns","description":"Campaign settings and assignments."},{"name":"Analytics","description":"Privacy-filtered aggregate analytics."},{"name":"Namespaces","description":"Namespaces and destination-domain mappings."},{"name":"Smart Paste","description":"Personal Smart Paste site settings."},{"name":"Pages","description":"Pages owned by a Pro personal account or Teams workspace owner key."},{"name":"Profile","description":"Personal profile and profile-link settings; unavailable to Teams workspace keys."}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"simpurl_<secret>","description":"Send the expiring secret as Authorization: Bearer simpurl_... ."}},"schemas":{"ApiError":{"type":"object","description":"Error response returned by the public API. Some plan and quota errors include additional fields.","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"plan":{"type":"string"},"limit":{"type":"integer"},"used":{"type":"integer"},"period_start":{"type":"string","format":"date-time"},"period_end":{"type":"string","format":"date-time"}},"additionalProperties":true},"UsageResponse":{"type":"object","additionalProperties":false,"required":["has_subscription","plan","limit","used","remaining","period","period_start","period_end","pending_change","analytics_preference","trial"],"properties":{"has_subscription":{"type":"boolean"},"plan":{"type":"string"},"limit":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"period":{"type":"string","enum":["rolling_30_days","billing_cycle"]},"period_start":{"type":"string","format":"date-time"},"period_end":{"type":"string","format":"date-time"},"pending_change":{"type":"object","nullable":true,"additionalProperties":false,"required":["plan","effective_at"],"properties":{"plan":{"type":"string"},"effective_at":{"type":"string","format":"date-time"}}},"analytics_preference":{"type":"object","additionalProperties":false,"required":["preferred_days","default_days","max_days"],"properties":{"preferred_days":{"type":"integer","nullable":true,"enum":[7,14,30,90,180,null]},"default_days":{"type":"integer","enum":[7,14,30,90,180]},"max_days":{"type":"integer","enum":[14,90,180]}}},"trial":{"type":"object","nullable":true,"additionalProperties":false,"required":["active","ends_at","notice_pending"],"properties":{"active":{"type":"boolean"},"ends_at":{"type":"string","format":"date-time","nullable":true},"notice_pending":{"type":"boolean"}}}}},"LinkSummary":{"type":"object","additionalProperties":false,"required":["id","short_code","destination_url","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"short_code":{"type":"string","example":"aB3xY7kQ"},"namespace_id":{"type":"string","format":"uuid","nullable":true},"namespace_name":{"type":"string","nullable":true},"slug":{"type":"string","nullable":true},"destination_url":{"type":"string","format":"uri"},"title":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"click_count":{"type":"integer","minimum":0},"is_active":{"type":"boolean"},"is_favorite":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"archived_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"campaign_id":{"type":"string","format":"uuid","nullable":true},"campaign_name":{"type":"string","nullable":true},"campaign_status":{"type":"string","nullable":true,"enum":["scheduled","active","completed","archived",null]},"namespace":{"description":"Internal undefined relation placeholder omitted by JSON serialization."},"campaign":{"description":"Internal undefined relation placeholder omitted by JSON serialization."}}},"LinkCursorResponse":{"type":"object","additionalProperties":false,"required":["mode","links","pagination"],"properties":{"mode":{"type":"string","enum":["cursor"]},"links":{"type":"array","items":{"$ref":"#/components/schemas/LinkSummary"}},"pagination":{"type":"object","additionalProperties":false,"required":["page_size","has_more","next_cursor"],"properties":{"page_size":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}},"CreateLinkResponse":{"type":"object","additionalProperties":false,"required":["link"],"properties":{"link":{"type":"object","additionalProperties":false,"required":["id","short_code","destination_url","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"short_code":{"type":"string","example":"aB3xY7kQ"},"namespace_id":{"type":"string","format":"uuid","nullable":true},"namespace_name":{"type":"string","nullable":true},"slug":{"type":"string","nullable":true},"canonical_path":{"type":"string","nullable":true},"destination_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"title":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"expires_at":{"type":"string","format":"date-time","nullable":true},"clerk_user_id":{"type":"string"},"campaign_id":{"type":"string","format":"uuid","nullable":true},"campaign_name":{"type":"string","nullable":true},"campaign_status":{"type":"string","nullable":true,"enum":["scheduled","active","completed","archived",null]}}}}},"DuplicateLinkResponse":{"type":"object","additionalProperties":false,"required":["duplicate","links"],"properties":{"duplicate":{"type":"boolean","enum":[true]},"links":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","short_code","destination_url","created_at","click_count","is_active","archived_at","expires_at","slug","namespace_name","canonical_path"],"properties":{"id":{"type":"string","format":"uuid"},"short_code":{"type":"string"},"destination_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"click_count":{"type":"integer","minimum":0},"is_active":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"slug":{"type":"string","nullable":true},"namespace_name":{"type":"string","nullable":true},"canonical_path":{"type":"string","nullable":true}}}}}},"UpdateLinkTagsResponse":{"type":"object","additionalProperties":false,"required":["id","tags"],"properties":{"id":{"type":"string","format":"uuid"},"tags":{"type":"array","items":{"type":"string"}}}},"SetLinkCampaignResponse":{"type":"object","additionalProperties":false,"required":["id","campaign_id","campaign_name","campaign_status"],"properties":{"id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string","format":"uuid","nullable":true},"campaign_name":{"type":"string","nullable":true},"campaign_status":{"type":"string","nullable":true,"enum":["scheduled","active","completed","archived",null]}}},"CampaignSummary":{"type":"object","additionalProperties":false,"required":["id","name","description","starts_at","ends_at","archived_at","tags","metadata","utm_parameters","created_at","updated_at","status","link_count"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time","nullable":true},"archived_at":{"type":"string","format":"date-time","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"utm_parameters":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","active","completed","archived"]},"link_count":{"type":"integer","minimum":0}}},"CampaignResponse":{"type":"object","additionalProperties":false,"required":["campaign"],"properties":{"campaign":{"$ref":"#/components/schemas/CampaignSummary"}}},"CampaignListResponse":{"type":"object","additionalProperties":false,"required":["campaigns"],"properties":{"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/CampaignSummary"}}}},"NamespaceSummary":{"type":"object","additionalProperties":false,"required":["id","name","created_at","link_count","has_been_used","can_use","can_edit","can_delete"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"link_count":{"type":"integer","minimum":0},"has_been_used":{"type":"boolean"},"can_use":{"type":"boolean"},"can_edit":{"type":"boolean"},"can_delete":{"type":"boolean"}}},"CreateNamespaceResponse":{"type":"object","additionalProperties":false,"required":["namespace"],"properties":{"namespace":{"type":"object","additionalProperties":false,"required":["id","name","created_at","link_count","has_been_used","can_edit","can_delete"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"link_count":{"type":"integer","minimum":0},"has_been_used":{"type":"boolean"},"can_edit":{"type":"boolean"},"can_delete":{"type":"boolean"}}}}},"NamespaceListResponse":{"type":"object","additionalProperties":false,"required":["plan","limit","used","remaining","namespaces"],"properties":{"plan":{"type":"string"},"limit":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"namespaces":{"type":"array","items":{"$ref":"#/components/schemas/NamespaceSummary"}}}},"Domain":{"type":"object","additionalProperties":false,"required":["id","namespace_id","domain","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"namespace_id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"DomainListResponse":{"type":"object","additionalProperties":false,"required":["plan","can_manage","domains"],"properties":{"plan":{"type":"string"},"can_manage":{"type":"boolean"},"domains":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}}}},"DomainResponse":{"type":"object","additionalProperties":false,"required":["domain"],"properties":{"domain":{"$ref":"#/components/schemas/Domain"}}},"SmartPasteDomain":{"type":"object","additionalProperties":false,"required":["id","domain","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"SmartPasteListResponse":{"type":"object","additionalProperties":false,"required":["plan","can_manage","domains"],"properties":{"plan":{"type":"string"},"can_manage":{"type":"boolean"},"domains":{"type":"array","items":{"$ref":"#/components/schemas/SmartPasteDomain"}}}},"SmartPasteResponse":{"type":"object","additionalProperties":false,"required":["domain"],"properties":{"domain":{"$ref":"#/components/schemas/SmartPasteDomain"}}},"DeleteResponse":{"type":"object","additionalProperties":false,"required":["id","deleted"],"properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","enum":[true]}}},"PageBlock":{"type":"object","additionalProperties":false,"required":["id","type"],"properties":{"id":{"type":"string","maxLength":64},"type":{"type":"string","enum":["link","heading","text","image","divider","media"]},"title":{"type":"string"},"text":{"type":"string"},"link_id":{"type":"string","format":"uuid"},"image_url":{"type":"string","format":"uri"},"image_alt":{"type":"string"},"caption":{"type":"string"},"short_url":{"type":"string","format":"uri"},"destination_url":{"type":"string","format":"uri"},"available":{"type":"boolean"}}},"PageContent":{"type":"object","additionalProperties":false,"required":["title","description","layout","theme","accent_color","cover_image_key","logo_image_key","show_branding","show_qr","blocks"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"layout":{"type":"string","enum":["stack","grid","editorial"]},"theme":{"type":"string","enum":["dark","light"]},"accent_color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"cover_image_key":{"type":"string","nullable":true},"logo_image_key":{"type":"string","nullable":true},"cover_image_url":{"type":"string","format":"uri","nullable":true},"logo_image_url":{"type":"string","format":"uri","nullable":true},"show_branding":{"type":"boolean"},"show_qr":{"type":"boolean"},"blocks":{"type":"array","maxItems":25,"items":{"$ref":"#/components/schemas/PageBlock"}}}},"PageSummary":{"type":"object","additionalProperties":false,"required":["id","name","slug","public_url","qr_url","published_at","archived_at","has_unpublished_changes","revision","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"public_url":{"type":"string","format":"uri"},"qr_url":{"type":"string","format":"uri"},"published_at":{"type":"string","format":"date-time","nullable":true},"archived_at":{"type":"string","format":"date-time","nullable":true},"has_unpublished_changes":{"type":"boolean"},"revision":{"type":"integer","minimum":1},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ManagedPage":{"type":"object","additionalProperties":false,"required":["id","name","slug","public_url","qr_url","published_at","archived_at","has_unpublished_changes","revision","created_at","updated_at","content"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"public_url":{"type":"string","format":"uri"},"qr_url":{"type":"string","format":"uri"},"published_at":{"type":"string","format":"date-time","nullable":true},"archived_at":{"type":"string","format":"date-time","nullable":true},"has_unpublished_changes":{"type":"boolean"},"revision":{"type":"integer","minimum":1},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"content":{"$ref":"#/components/schemas/PageContent"}}},"PageListResponse":{"type":"object","additionalProperties":false,"required":["pages","limit","plan","allowed"],"properties":{"pages":{"type":"array","items":{"$ref":"#/components/schemas/PageSummary"}},"limit":{"type":"integer","minimum":0},"plan":{"type":"string"},"allowed":{"type":"boolean"}}},"PageResponse":{"type":"object","additionalProperties":false,"required":["page"],"properties":{"page":{"$ref":"#/components/schemas/ManagedPage"}}},"PageAnalyticsResponse":{"type":"object","additionalProperties":false,"required":["days","views","engaged_views","clicks","engagement_rate","daily","blocks","sources","channels"],"properties":{"days":{"type":"integer","enum":[7,14,30,90,180]},"views":{"type":"integer","minimum":0},"engaged_views":{"type":"integer","minimum":0},"clicks":{"type":"integer","minimum":0},"engagement_rate":{"type":"number","minimum":0,"maximum":100},"daily":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["date","views","clicks"],"properties":{"date":{"type":"string","format":"date"},"views":{"type":"integer","minimum":0},"clicks":{"type":"integer","minimum":0}}}},"blocks":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["block_id","title","clicks"],"properties":{"block_id":{"type":"string"},"title":{"type":"string"},"clicks":{"type":"integer","minimum":0}}}},"sources":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["source_host","views","clicks"],"properties":{"source_host":{"type":"string","nullable":true},"views":{"type":"integer","minimum":0},"clicks":{"type":"integer","minimum":0}}}},"channels":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["source","views","clicks"],"properties":{"source":{"type":"string","enum":["direct","qr"]},"views":{"type":"integer","minimum":0},"clicks":{"type":"integer","minimum":0}}}}}},"ProfileSummary":{"type":"object","additionalProperties":false,"required":["handle","display_name","bio","is_public","show_qr","background_theme","photo_filter","photo_presentation","link_layout","link_shine_enabled","photo_url","created_at","updated_at"],"properties":{"handle":{"type":"string"},"display_name":{"type":"string"},"bio":{"type":"string","nullable":true},"is_public":{"type":"boolean"},"show_qr":{"type":"boolean"},"background_theme":{"type":"string","enum":["blank","aurora","center_glow","diagonal","horizon","prism"]},"photo_filter":{"type":"string","enum":["original","grayscale","black_white","sepia","warm","cool"]},"photo_presentation":{"type":"string","enum":["avatar","cover"]},"link_layout":{"type":"string","enum":["classic","grid","orbit","icon_wall","spotlight","compact"]},"link_shine_enabled":{"type":"boolean"},"photo_url":{"type":"string","format":"uri","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ProfileHandleChanges":{"type":"object","additionalProperties":false,"required":["limit","window_days","used","remaining","next_available_at"],"properties":{"limit":{"type":"integer","minimum":0},"window_days":{"type":"integer","minimum":0},"used":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0},"next_available_at":{"type":"string","format":"date-time","nullable":true}}},"ProfileMedia":{"type":"object","nullable":true,"additionalProperties":false,"required":["provider","kind","embed_url","height"],"properties":{"provider":{"type":"string","enum":["youtube","vimeo","spotify","soundcloud"]},"kind":{"type":"string","enum":["video","audio"]},"embed_url":{"type":"string","format":"uri"},"height":{"type":"integer","minimum":0}}},"ProfileLinkSummary":{"type":"object","additionalProperties":false,"required":["id","link_id","title","custom_icon_url","position","publicly_usable","display_mode","is_featured","card_size","emphasis_effect","description","section_title","media_mode","visible_from","visible_until","media","platform","short_code","short_url","destination_url","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"link_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"custom_icon_url":{"type":"string","format":"uri","nullable":true},"position":{"type":"integer","minimum":0},"publicly_usable":{"type":"boolean"},"display_mode":{"type":"string","enum":["icon_title","icon_only","title_only"]},"is_featured":{"type":"boolean"},"card_size":{"type":"string","enum":["standard","wide"]},"emphasis_effect":{"type":"string","enum":["none","wiggle","pulse","glow"]},"description":{"type":"string","nullable":true},"section_title":{"type":"string","nullable":true},"media_mode":{"type":"string","enum":["link","embed"]},"visible_from":{"type":"string","format":"date-time","nullable":true},"visible_until":{"type":"string","format":"date-time","nullable":true},"media":{"$ref":"#/components/schemas/ProfileMedia"},"platform":{"type":"string"},"short_code":{"type":"string"},"short_url":{"type":"string","format":"uri"},"destination_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ProfileResponse":{"type":"object","additionalProperties":false,"required":["plan","allowed","link_limit","handle_changes","profile","links"],"properties":{"plan":{"type":"string"},"allowed":{"type":"boolean"},"link_limit":{"type":"integer","minimum":0},"handle_changes":{"$ref":"#/components/schemas/ProfileHandleChanges"},"profile":{"oneOf":[{"$ref":"#/components/schemas/ProfileSummary"},{"type":"object","nullable":true,"enum":[null]}]},"links":{"type":"array","items":{"$ref":"#/components/schemas/ProfileLinkSummary"}}}},"SaveProfileResponse":{"type":"object","additionalProperties":false,"required":["profile","handle_changes"],"properties":{"profile":{"$ref":"#/components/schemas/ProfileSummary"},"handle_changes":{"$ref":"#/components/schemas/ProfileHandleChanges"}}},"ProfileLinkResponse":{"type":"object","additionalProperties":false,"required":["link","links"],"properties":{"link":{"$ref":"#/components/schemas/ProfileLinkSummary"},"links":{"type":"array","items":{"$ref":"#/components/schemas/ProfileLinkSummary"}}}},"ProfileLinksResponse":{"type":"object","additionalProperties":false,"required":["links"],"properties":{"links":{"type":"array","items":{"$ref":"#/components/schemas/ProfileLinkSummary"}}}},"AnalyticsDimension":{"type":"object","additionalProperties":false,"required":["label","count"],"properties":{"label":{"type":"string"},"count":{"type":"integer","minimum":0}}},"AnalyticsScope":{"oneOf":[{"type":"object","additionalProperties":false,"required":["kind"],"properties":{"kind":{"type":"string","enum":["account"]}}},{"type":"object","additionalProperties":false,"required":["kind","campaign_id","campaign_name"],"properties":{"kind":{"type":"string","enum":["campaign"]},"campaign_id":{"type":"string","format":"uuid"},"campaign_name":{"type":"string"}}}]},"AnalyticsSummaryResponse":{"type":"object","additionalProperties":false,"required":["scope","days","range","total_clicks","truncated","sources","browsers","operating_systems","time_of_day_utc","popular_links"],"properties":{"scope":{"$ref":"#/components/schemas/AnalyticsScope"},"days":{"type":"integer","enum":[7,14,30,90,180]},"range":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"total_clicks":{"type":"integer","minimum":0},"truncated":{"type":"boolean","description":"True when the newest 20,000 event cap was reached."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsDimension"}},"browsers":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsDimension"}},"operating_systems":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsDimension"}},"time_of_day_utc":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsDimension"}},"popular_links":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/AnalyticsLink"}}}},"AnalyticsLink":{"type":"object","additionalProperties":false,"required":["link_id","short_code","namespace_name","slug","canonical_path","destination_url","count"],"properties":{"link_id":{"type":"string","format":"uuid"},"short_code":{"type":"string","nullable":true},"namespace_name":{"type":"string","nullable":true},"slug":{"type":"string","nullable":true},"canonical_path":{"type":"string","nullable":true},"destination_url":{"type":"string","nullable":true},"count":{"type":"integer","minimum":0}}},"CampaignAnalyticsLink":{"type":"object","additionalProperties":false,"required":["link_id","short_code","namespace_name","slug","canonical_path","destination_url","count"],"properties":{"link_id":{"type":"string","format":"uuid"},"short_code":{"type":"string"},"namespace_name":{"type":"string","nullable":true},"slug":{"type":"string","nullable":true},"canonical_path":{"type":"string","nullable":true},"destination_url":{"type":"string","format":"uri"},"count":{"type":"integer","minimum":0}}},"CampaignAnalyticsResponse":{"type":"object","additionalProperties":false,"required":["campaign","days","range","total_clicks","unique_visitors","hub_views","truncated","mapped_links","top_links","sources","browsers","operating_systems"],"properties":{"campaign":{"$ref":"#/components/schemas/CampaignSummary"},"days":{"type":"integer","enum":[7,14,30,90,180]},"range":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"total_clicks":{"type":"integer","minimum":0},"unique_visitors":{"type":"integer","minimum":0},"hub_views":{"type":"object","additionalProperties":false,"required":["total","direct","qr","unique_visitors"],"properties":{"total":{"type":"integer","minimum":0},"direct":{"type":"integer","minimum":0},"qr":{"type":"integer","minimum":0},"unique_visitors":{"type":"integer","minimum":0},"events":{"description":"Internal undefined placeholder omitted by JSON serialization."}}},"truncated":{"type":"boolean","description":"True when the click or hub-view newest 20,000 row cap was reached."},"mapped_links":{"type":"array","items":{"$ref":"#/components/schemas/CampaignAnalyticsLink"}},"top_links":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/CampaignAnalyticsLink"}},"sources":{"type":"array","maxItems":8,"items":{"$ref":"#/components/schemas/AnalyticsDimension"}},"browsers":{"type":"array","maxItems":8,"items":{"$ref":"#/components/schemas/AnalyticsDimension"}},"operating_systems":{"type":"array","maxItems":8,"items":{"$ref":"#/components/schemas/AnalyticsDimension"}}}}}},"paths":{"/pages":{"get":{"operationId":"get_pages","summary":"List Pages and publication status","description":"Lists all Pages owned by the account, including archived Pages. Page content is returned by the individual Page endpoint. Required permission: pages:read. Account quotas and ownership checks apply.","tags":["Pages"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"pages:read","x-required-permission":"pages:read","parameters":[],"responses":{"200":{"description":"The account's Page summaries and plan capability.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageListResponse"},"example":{"pages":[{"id":"55555555-5555-4555-8555-555555555555","name":"Launch links","slug":"launch-links","public_url":"https://go.simpurl.click/pages/launch-links","qr_url":"https://go.simpurl.click/pages/launch-links?source=qr","published_at":null,"archived_at":null,"has_unpublished_changes":true,"revision":1,"created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z"}],"limit":10,"plan":"pro","allowed":true}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}},"post":{"operationId":"post_pages","summary":"Create a Page draft","description":"Creates a new draft Page, within the limit of 10 nonarchived Pages and 25 blocks per Page. New Pages start unpublished and have null cover_image_key and logo_image_key values. Upload cover and logo images through the SimpURL app; this API has no asset-upload operation. Required permission: pages:write. Account quotas and ownership checks apply.","tags":["Pages"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"pages:write","x-required-permission":"pages:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"slug":{"type":"string","minLength":3,"maxLength":64},"content":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":160},"description":{"type":"string","minLength":1,"maxLength":400},"layout":{"type":"string","enum":["stack","grid","editorial"]},"theme":{"type":"string","enum":["dark","light"]},"accent_color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"cover_image_key":{"enum":[null],"nullable":true,"type":"object"},"logo_image_key":{"enum":[null],"nullable":true,"type":"object"},"show_branding":{"type":"boolean"},"show_qr":{"type":"boolean"},"blocks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"type":{"type":"string","enum":["link","heading","text","image","divider","media"]},"title":{"type":"string","maxLength":160},"text":{"type":"string","maxLength":4000},"link_id":{"type":"string","format":"uuid"},"image_url":{"type":"string","format":"uri","maxLength":2048},"image_alt":{"type":"string","maxLength":160},"caption":{"type":"string","maxLength":300}},"required":["id","type"],"additionalProperties":false},"maxItems":25}},"required":["title","description","layout","theme","accent_color","show_branding","show_qr","blocks"],"additionalProperties":false}},"required":["name","slug","content"],"additionalProperties":false},"example":{"name":"Launch links","slug":"launch-links","content":{"title":"Launch links","description":"A simple collection of launch links.","layout":"stack","theme":"light","accent_color":"#2563eb","cover_image_key":null,"logo_image_key":null,"show_branding":true,"show_qr":true,"blocks":[{"id":"intro","type":"heading","title":"Launch"}]}}}}},"responses":{"201":{"description":"The newly created draft Page.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageResponse"},"example":{"page":{"id":"55555555-5555-4555-8555-555555555555","name":"Launch links","slug":"launch-links","public_url":"https://go.simpurl.click/pages/launch-links","qr_url":"https://go.simpurl.click/pages/launch-links?source=qr","published_at":null,"archived_at":null,"has_unpublished_changes":true,"revision":1,"created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z","content":{"title":"Launch links","description":"A simple collection of launch links.","layout":"stack","theme":"light","accent_color":"#2563eb","cover_image_key":null,"logo_image_key":null,"show_branding":true,"show_qr":true,"blocks":[{"id":"intro","type":"heading","title":"Launch"}],"cover_image_url":null,"logo_image_url":null}}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"409":{"description":"The request conflicts with the current resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"The resource cannot be changed in its current state."}}}},"413":{"description":"The JSON request body is larger than 32 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Request body is too large."}}}},"415":{"description":"The request body must use JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"unsupported_media_type","error":"Use Content-Type: application/json."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/pages/{id}":{"get":{"operationId":"get_pages_id_","summary":"Read a Page draft","description":"Returns an owned Page draft, including its complete content and cover/logo image keys. Existing uploaded image keys must be sent back unchanged when replacing the draft. Required permission: pages:read. Account quotas and ownership checks apply.","tags":["Pages"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"pages:read","x-required-permission":"pages:read","parameters":[{"name":"id","in":"path","required":true,"description":"Owned resource UUID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The owned Page with its complete draft content.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageResponse"},"example":{"page":{"id":"55555555-5555-4555-8555-555555555555","name":"Launch links","slug":"launch-links","public_url":"https://go.simpurl.click/pages/launch-links","qr_url":"https://go.simpurl.click/pages/launch-links?source=qr","published_at":null,"archived_at":null,"has_unpublished_changes":true,"revision":1,"created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z","content":{"title":"Launch links","description":"A simple collection of launch links.","layout":"stack","theme":"light","accent_color":"#2563eb","cover_image_key":null,"logo_image_key":null,"show_branding":true,"show_qr":true,"blocks":[{"id":"intro","type":"heading","title":"Launch"}],"cover_image_url":null,"logo_image_url":null}}}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}},"put":{"operationId":"put_pages_id_","summary":"Replace a Page draft","description":"Replaces the complete Page draft for the path id. Send name, slug, revision, and the full write content document; strip read-only cover_image_url, logo_image_url, and derived block fields before sending. Include any cover_image_key and logo_image_key returned by GET to preserve uploaded assets; omitting either key clears that reference. This public API has no asset-upload operation. A stale revision returns 409; GET the Page and retry with the current revision. Required permission: pages:write. Account quotas and ownership checks apply.","tags":["Pages"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"pages:write","x-required-permission":"pages:write","parameters":[{"name":"id","in":"path","required":true,"description":"Owned resource UUID.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"slug":{"type":"string","minLength":3,"maxLength":64},"content":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":160},"description":{"type":"string","minLength":1,"maxLength":400},"layout":{"type":"string","enum":["stack","grid","editorial"]},"theme":{"type":"string","enum":["dark","light"]},"accent_color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"cover_image_key":{"type":"string","maxLength":512,"nullable":true},"logo_image_key":{"type":"string","maxLength":512,"nullable":true},"show_branding":{"type":"boolean"},"show_qr":{"type":"boolean"},"blocks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"type":{"type":"string","enum":["link","heading","text","image","divider","media"]},"title":{"type":"string","maxLength":160},"text":{"type":"string","maxLength":4000},"link_id":{"type":"string","format":"uuid"},"image_url":{"type":"string","format":"uri","maxLength":2048},"image_alt":{"type":"string","maxLength":160},"caption":{"type":"string","maxLength":300}},"required":["id","type"],"additionalProperties":false},"maxItems":25}},"required":["title","description","layout","theme","accent_color","show_branding","show_qr","blocks"],"additionalProperties":false},"revision":{"type":"integer","minimum":1,"maximum":9007199254740991}},"required":["name","slug","content","revision"],"additionalProperties":false},"example":{"name":"Launch links","slug":"launch-links","revision":1,"content":{"title":"Launch links","description":"A simple collection of launch links.","layout":"stack","theme":"light","accent_color":"#2563eb","cover_image_key":"pages/55555555-5555-4555-8555-555555555555/cover/77777777-7777-4777-8777-777777777777.webp","logo_image_key":"pages/55555555-5555-4555-8555-555555555555/logo/77777777-7777-4777-8777-777777777777.webp","show_branding":true,"show_qr":true,"blocks":[{"id":"intro","type":"heading","title":"Launch"}]}}}}},"responses":{"200":{"description":"The replaced Page draft.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageResponse"},"example":{"page":{"id":"55555555-5555-4555-8555-555555555555","name":"Launch links","slug":"launch-links","public_url":"https://go.simpurl.click/pages/launch-links","qr_url":"https://go.simpurl.click/pages/launch-links?source=qr","published_at":null,"archived_at":null,"has_unpublished_changes":true,"revision":2,"created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:05:00.000Z","content":{"title":"Launch links","description":"A simple collection of launch links.","layout":"stack","theme":"light","accent_color":"#2563eb","cover_image_key":"pages/55555555-5555-4555-8555-555555555555/cover/77777777-7777-4777-8777-777777777777.webp","logo_image_key":"pages/55555555-5555-4555-8555-555555555555/logo/77777777-7777-4777-8777-777777777777.webp","show_branding":true,"show_qr":true,"blocks":[{"id":"intro","type":"heading","title":"Launch"}],"cover_image_url":"https://cdn.example.com/pages/cover.webp","logo_image_url":"https://cdn.example.com/pages/logo.webp"}}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"409":{"description":"The request conflicts with the current resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"The resource cannot be changed in its current state."}}}},"413":{"description":"The JSON request body is larger than 32 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Request body is too large."}}}},"415":{"description":"The request body must use JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"unsupported_media_type","error":"Use Content-Type: application/json."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/pages/{id}/publish":{"post":{"operationId":"post_pages_id_publish","summary":"Publish the current Page draft","description":"Publishes the current Page draft using the supplied revision. Publishing is explicit and is never performed automatically after a draft save. A stale revision returns 409; GET the Page and retry with the current revision. Required permission: pages:write. Account quotas and ownership checks apply.","tags":["Pages"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"pages:write","x-required-permission":"pages:write","parameters":[{"name":"id","in":"path","required":true,"description":"Owned resource UUID.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"revision":{"type":"integer","minimum":1,"maximum":9007199254740991}},"required":["revision"],"additionalProperties":false},"example":{"revision":1}}}},"responses":{"200":{"description":"The published Page.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageResponse"},"example":{"page":{"id":"55555555-5555-4555-8555-555555555555","name":"Launch links","slug":"launch-links","public_url":"https://go.simpurl.click/pages/launch-links","qr_url":"https://go.simpurl.click/pages/launch-links?source=qr","published_at":"2026-09-29T12:10:00.000Z","archived_at":null,"has_unpublished_changes":false,"revision":1,"created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z","content":{"title":"Launch links","description":"A simple collection of launch links.","layout":"stack","theme":"light","accent_color":"#2563eb","cover_image_key":null,"logo_image_key":null,"show_branding":true,"show_qr":true,"blocks":[{"id":"intro","type":"heading","title":"Launch"}],"cover_image_url":null,"logo_image_url":null}}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"409":{"description":"The request conflicts with the current resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"The resource cannot be changed in its current state."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/pages/{id}/unpublish":{"post":{"operationId":"post_pages_id_unpublish","summary":"Unpublish a Page","description":"Unpublishes the Page using the supplied revision. A stale revision returns 409; GET the Page and retry with the current revision. Required permission: pages:write. Account quotas and ownership checks apply.","tags":["Pages"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"pages:write","x-required-permission":"pages:write","parameters":[{"name":"id","in":"path","required":true,"description":"Owned resource UUID.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"revision":{"type":"integer","minimum":1,"maximum":9007199254740991}},"required":["revision"],"additionalProperties":false},"example":{"revision":1}}}},"responses":{"200":{"description":"The unpublished Page.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageResponse"},"example":{"page":{"id":"55555555-5555-4555-8555-555555555555","name":"Launch links","slug":"launch-links","public_url":"https://go.simpurl.click/pages/launch-links","qr_url":"https://go.simpurl.click/pages/launch-links?source=qr","published_at":null,"archived_at":null,"has_unpublished_changes":true,"revision":1,"created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z","content":{"title":"Launch links","description":"A simple collection of launch links.","layout":"stack","theme":"light","accent_color":"#2563eb","cover_image_key":null,"logo_image_key":null,"show_branding":true,"show_qr":true,"blocks":[{"id":"intro","type":"heading","title":"Launch"}],"cover_image_url":null,"logo_image_url":null}}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"409":{"description":"The request conflicts with the current resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"The resource cannot be changed in its current state."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/pages/{id}/archive":{"put":{"operationId":"put_pages_id_archive","summary":"Archive or restore a Page","description":"Sets the Page archived state using the supplied revision. A stale revision returns 409; GET the Page and retry with the current revision. Required permission: pages:write. Account quotas and ownership checks apply.","tags":["Pages"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"pages:write","x-required-permission":"pages:write","parameters":[{"name":"id","in":"path","required":true,"description":"Owned resource UUID.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"revision":{"type":"integer","minimum":1,"maximum":9007199254740991},"archived":{"type":"boolean"}},"required":["revision","archived"],"additionalProperties":false},"example":{"revision":1,"archived":true}}}},"responses":{"200":{"description":"The Page with its updated archived state.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageResponse"},"example":{"page":{"id":"55555555-5555-4555-8555-555555555555","name":"Launch links","slug":"launch-links","public_url":"https://go.simpurl.click/pages/launch-links","qr_url":"https://go.simpurl.click/pages/launch-links?source=qr","published_at":null,"archived_at":"2026-09-29T12:15:00.000Z","has_unpublished_changes":true,"revision":1,"created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z","content":{"title":"Launch links","description":"A simple collection of launch links.","layout":"stack","theme":"light","accent_color":"#2563eb","cover_image_key":null,"logo_image_key":null,"show_branding":true,"show_qr":true,"blocks":[{"id":"intro","type":"heading","title":"Launch"}],"cover_image_url":null,"logo_image_url":null}}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"409":{"description":"The request conflicts with the current resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"The resource cannot be changed in its current state."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/pages/{id}/analytics":{"get":{"operationId":"get_pages_id_analytics","summary":"Read aggregate Page analytics","description":"Returns aggregate Page analytics for the requested 7, 14, 30, 90, or 180 calendar-day window. Page analytics has no 20,000-row event cap and returns no raw visitor identifiers. Required permission: analytics:read. Account quotas and ownership checks apply.","tags":["Analytics"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"analytics:read","x-required-permission":"analytics:read","parameters":[{"name":"id","in":"path","required":true,"description":"Owned resource UUID.","schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","required":false,"description":"Analytics window in calendar days.","schema":{"type":"integer","enum":[7,14,30,90,180],"default":30}}],"responses":{"200":{"description":"Aggregate privacy-safe Page analytics.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageAnalyticsResponse"},"example":{"days":30,"views":128,"engaged_views":64,"clicks":72,"engagement_rate":50,"daily":[{"date":"2026-09-28","views":20,"clicks":12},{"date":"2026-09-29","views":24,"clicks":16}],"blocks":[{"block_id":"intro","title":"Launch","clicks":16}],"sources":[{"source_host":null,"views":80,"clicks":42},{"source_host":"newsletter.example","views":48,"clicks":30}],"channels":[{"source":"direct","views":90,"clicks":48},{"source":"qr","views":38,"clicks":24}]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/profile":{"get":{"operationId":"get_profile","summary":"Read your personal profile and links","description":"Returns the personal profile, owned profile links, plan capability, and handle-change policy. This endpoint is personal-only and is unavailable to Teams workspace keys. Required permission: profile:read. Account quotas and ownership checks apply.","tags":["Profile"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"profile:read","x-required-permission":"profile:read","parameters":[],"responses":{"200":{"description":"The personal profile and its owned links.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"},"example":{"plan":"pro","allowed":true,"link_limit":14,"handle_changes":{"limit":2,"window_days":45,"used":0,"remaining":2,"next_available_at":null},"profile":{"handle":"alex-example","display_name":"Alex Example","bio":"Links and projects.","is_public":true,"show_qr":true,"background_theme":"blank","photo_filter":"original","photo_presentation":"avatar","link_layout":"classic","link_shine_enabled":false,"photo_url":null,"created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z"},"links":[{"id":"66666666-6666-4666-8666-666666666666","link_id":"11111111-1111-4111-8111-111111111111","title":"Documentation","custom_icon_url":null,"position":0,"publicly_usable":true,"display_mode":"icon_title","is_featured":false,"card_size":"standard","emphasis_effect":"none","description":null,"section_title":null,"media_mode":"link","visible_from":null,"visible_until":null,"media":null,"platform":"website","short_code":"aB3xY7kQ","short_url":"https://go.simpurl.click/aB3xY7kQ","destination_url":"https://example.com/docs","created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z"}]}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}},"put":{"operationId":"put_profile","summary":"Create or update your personal profile","description":"Creates or updates the personal profile basics. handle, display_name, is_public, and show_qr are required; an omitted bio clears the bio. Appearance fields are optional, and omitting them preserves their stored values. The existing photo is preserved. Profile address changes are limited to two in a rolling 45-day window; a 429 with code PROFILE_HANDLE_CHANGE_LIMIT includes handle_changes.next_available_at and is not a per-minute rate limit. Required permission: profile:write. Account quotas and ownership checks apply.","tags":["Profile"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"profile:write","x-required-permission":"profile:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string","minLength":3,"maxLength":30},"display_name":{"type":"string","minLength":1,"maxLength":60},"bio":{"type":"string","maxLength":160,"nullable":true},"is_public":{"type":"boolean"},"show_qr":{"type":"boolean"},"background_theme":{"type":"string","enum":["blank","aurora","center_glow","diagonal","horizon","prism"]},"photo_filter":{"type":"string","enum":["original","grayscale","black_white","sepia","warm","cool"]},"photo_presentation":{"type":"string","enum":["avatar","cover"]},"link_layout":{"type":"string","enum":["classic","grid","orbit","icon_wall","spotlight","compact"]},"link_shine_enabled":{"type":"boolean"}},"required":["handle","display_name","is_public","show_qr"],"additionalProperties":false},"example":{"handle":"alex-example","display_name":"Alex Example","bio":"Links and projects.","is_public":true,"show_qr":true,"background_theme":"blank","photo_filter":"original","photo_presentation":"avatar","link_layout":"classic","link_shine_enabled":false}}}},"responses":{"200":{"description":"The saved personal profile and handle-change policy.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveProfileResponse"},"example":{"profile":{"handle":"alex-example","display_name":"Alex Example","bio":"Links and projects.","is_public":true,"show_qr":true,"background_theme":"blank","photo_filter":"original","photo_presentation":"avatar","link_layout":"classic","link_shine_enabled":false,"photo_url":null,"created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z"},"handle_changes":{"limit":2,"window_days":45,"used":0,"remaining":2,"next_available_at":null}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"409":{"description":"The request conflicts with the current resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"The resource cannot be changed in its current state."}}}},"413":{"description":"The JSON request body is larger than 32 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Request body is too large."}}}},"415":{"description":"The request body must use JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"unsupported_media_type","error":"Use Content-Type: application/json."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/profile/links":{"post":{"operationId":"post_profile_links","summary":"Add an existing short link to your profile","description":"Adds an already-created, owned short link to the personal profile. This operation does not create a short link or auto-create one; create the short link separately with POST /links using links:write, then submit its link_id here. Required permission: profile:write. Account quotas and ownership checks apply.","tags":["Profile"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"profile:write","x-required-permission":"profile:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"link_id":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":80},"custom_icon_url":{"type":"string","format":"uri","maxLength":2048,"nullable":true},"display_mode":{"type":"string","enum":["icon_title","icon_only","title_only"]},"card_size":{"type":"string","enum":["standard","wide"]},"is_featured":{"type":"boolean"},"emphasis_effect":{"type":"string","enum":["none","wiggle","pulse","glow"]},"description":{"type":"string","maxLength":160,"nullable":true},"section_title":{"type":"string","maxLength":40,"nullable":true},"media_mode":{"type":"string","enum":["link","embed"]},"visible_from":{"type":"string","format":"date-time","nullable":true},"visible_until":{"type":"string","format":"date-time","nullable":true}},"required":["link_id","title"],"additionalProperties":false},"example":{"link_id":"11111111-1111-4111-8111-111111111111","title":"Documentation","display_mode":"icon_title","is_featured":false,"card_size":"standard","emphasis_effect":"none","description":null,"section_title":null,"media_mode":"link","visible_from":null,"visible_until":null}}}},"responses":{"201":{"description":"The created profile link and the resulting ordered link list.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileLinkResponse"},"example":{"link":{"id":"66666666-6666-4666-8666-666666666666","link_id":"11111111-1111-4111-8111-111111111111","title":"Documentation","custom_icon_url":null,"position":0,"publicly_usable":true,"display_mode":"icon_title","is_featured":false,"card_size":"standard","emphasis_effect":"none","description":null,"section_title":null,"media_mode":"link","visible_from":null,"visible_until":null,"media":null,"platform":"website","short_code":"aB3xY7kQ","short_url":"https://go.simpurl.click/aB3xY7kQ","destination_url":"https://example.com/docs","created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z"},"links":[{"id":"66666666-6666-4666-8666-666666666666","link_id":"11111111-1111-4111-8111-111111111111","title":"Documentation","custom_icon_url":null,"position":0,"publicly_usable":true,"display_mode":"icon_title","is_featured":false,"card_size":"standard","emphasis_effect":"none","description":null,"section_title":null,"media_mode":"link","visible_from":null,"visible_until":null,"media":null,"platform":"website","short_code":"aB3xY7kQ","short_url":"https://go.simpurl.click/aB3xY7kQ","destination_url":"https://example.com/docs","created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z"}]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"409":{"description":"The request conflicts with the current resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"The resource cannot be changed in its current state."}}}},"413":{"description":"The JSON request body is larger than 32 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Request body is too large."}}}},"415":{"description":"The request body must use JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"unsupported_media_type","error":"Use Content-Type: application/json."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/profile/links/{id}":{"put":{"operationId":"put_profile_links_id_","summary":"Update a profile link","description":"Updates an owned profile placement using its UUID in the path. link_id and title are required; omitted optional placement fields are preserved. The referenced short link must already exist and belong to the account; this operation does not create links. Required permission: profile:write. Account quotas and ownership checks apply.","tags":["Profile"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"profile:write","x-required-permission":"profile:write","parameters":[{"name":"id","in":"path","required":true,"description":"Owned resource UUID.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"link_id":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":80},"custom_icon_url":{"type":"string","format":"uri","maxLength":2048,"nullable":true},"display_mode":{"type":"string","enum":["icon_title","icon_only","title_only"]},"card_size":{"type":"string","enum":["standard","wide"]},"is_featured":{"type":"boolean"},"emphasis_effect":{"type":"string","enum":["none","wiggle","pulse","glow"]},"description":{"type":"string","maxLength":160,"nullable":true},"section_title":{"type":"string","maxLength":40,"nullable":true},"media_mode":{"type":"string","enum":["link","embed"]},"visible_from":{"type":"string","format":"date-time","nullable":true},"visible_until":{"type":"string","format":"date-time","nullable":true}},"required":["link_id","title"],"additionalProperties":false},"example":{"link_id":"11111111-1111-4111-8111-111111111111","title":"Documentation","display_mode":"icon_title","is_featured":false,"card_size":"standard","emphasis_effect":"none","description":null,"section_title":null,"media_mode":"link","visible_from":null,"visible_until":null}}}},"responses":{"200":{"description":"The updated profile link and the resulting ordered link list.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileLinkResponse"},"example":{"link":{"id":"66666666-6666-4666-8666-666666666666","link_id":"11111111-1111-4111-8111-111111111111","title":"Documentation","custom_icon_url":null,"position":0,"publicly_usable":true,"display_mode":"icon_title","is_featured":false,"card_size":"standard","emphasis_effect":"none","description":null,"section_title":null,"media_mode":"link","visible_from":null,"visible_until":null,"media":null,"platform":"website","short_code":"aB3xY7kQ","short_url":"https://go.simpurl.click/aB3xY7kQ","destination_url":"https://example.com/docs","created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z"},"links":[{"id":"66666666-6666-4666-8666-666666666666","link_id":"11111111-1111-4111-8111-111111111111","title":"Documentation","custom_icon_url":null,"position":0,"publicly_usable":true,"display_mode":"icon_title","is_featured":false,"card_size":"standard","emphasis_effect":"none","description":null,"section_title":null,"media_mode":"link","visible_from":null,"visible_until":null,"media":null,"platform":"website","short_code":"aB3xY7kQ","short_url":"https://go.simpurl.click/aB3xY7kQ","destination_url":"https://example.com/docs","created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z"}]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"409":{"description":"The request conflicts with the current resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"The resource cannot be changed in its current state."}}}},"413":{"description":"The JSON request body is larger than 32 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Request body is too large."}}}},"415":{"description":"The request body must use JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"unsupported_media_type","error":"Use Content-Type: application/json."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}},"delete":{"operationId":"delete_profile_links_id_","summary":"Remove a link from your profile","description":"Removes an owned profile placement using its UUID in the path and returns the remaining ordered placements. The underlying short link remains active and is not deleted. Required permission: profile:write. Account quotas and ownership checks apply.","tags":["Profile"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"profile:write","x-required-permission":"profile:write","parameters":[{"name":"id","in":"path","required":true,"description":"Owned resource UUID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The remaining ordered profile links.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileLinksResponse"},"example":{"links":[]}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/profile/links/order":{"put":{"operationId":"put_profile_links_order","summary":"Reorder all profile links","description":"Replaces profile-link ordering. ordered_ids must contain every current owned profile-link UUID exactly once. Required permission: profile:write. Account quotas and ownership checks apply.","tags":["Profile"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"profile:write","x-required-permission":"profile:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ordered_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":14}},"required":["ordered_ids"],"additionalProperties":false},"example":{"ordered_ids":["66666666-6666-4666-8666-666666666666"]}}}},"responses":{"200":{"description":"The reordered profile links.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileLinksResponse"},"example":{"links":[{"id":"66666666-6666-4666-8666-666666666666","link_id":"11111111-1111-4111-8111-111111111111","title":"Documentation","custom_icon_url":null,"position":0,"publicly_usable":true,"display_mode":"icon_title","is_featured":false,"card_size":"standard","emphasis_effect":"none","description":null,"section_title":null,"media_mode":"link","visible_from":null,"visible_until":null,"media":null,"platform":"website","short_code":"aB3xY7kQ","short_url":"https://go.simpurl.click/aB3xY7kQ","destination_url":"https://example.com/docs","created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z"}]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"409":{"description":"The request conflicts with the current resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"The resource cannot be changed in its current state."}}}},"413":{"description":"The JSON request body is larger than 32 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Request body is too large."}}}},"415":{"description":"The request body must use JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"unsupported_media_type","error":"Use Content-Type: application/json."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/account":{"get":{"operationId":"get_account","summary":"Read plan and link usage","description":"Returns the account plan, link quota window, pending subscription change, trial state, and analytics-day preferences. Required permission: links:read. Account quotas and ownership checks apply.","tags":["Account"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"links:read","x-required-permission":"links:read","parameters":[],"responses":{"200":{"description":"Account usage and plan context.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"},"example":{"has_subscription":true,"plan":"pro","limit":200,"used":42,"remaining":318,"period":"billing_cycle","period_start":"2026-09-01T00:00:00.000Z","period_end":"2026-10-01T00:00:00.000Z","pending_change":null,"analytics_preference":{"preferred_days":30,"default_days":30,"max_days":180},"trial":null}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/links":{"get":{"operationId":"get_links","summary":"List links with cursor pagination","description":"Lists non-deleted links using cursor pagination. The public API forces cursor mode; pass the returned next_cursor with the same filters to continue. Archived links are not included by this route. Required permission: links:read. Account quotas and ownership checks apply.","tags":["Links"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"links:read","x-required-permission":"links:read","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"tags","in":"query","required":false,"schema":{"type":"string","maxLength":650}},{"name":"namespace_ids","in":"query","required":false,"schema":{"type":"string","maxLength":1900}},{"name":"campaign_ids","in":"query","required":false,"schema":{"type":"string","maxLength":1900}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["recent","oldest","popular"],"default":"recent"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned in the previous response; keep all other filters unchanged.","schema":{"type":"string","maxLength":768}}],"responses":{"200":{"description":"A cursor-paginated link collection.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkCursorResponse"},"example":{"mode":"cursor","links":[{"id":"11111111-1111-4111-8111-111111111111","short_code":"aB3xY7kQ","namespace_id":null,"namespace_name":null,"slug":null,"destination_url":"https://example.com/docs","title":"Documentation","created_at":"2026-09-29T12:00:00.000Z","click_count":12,"is_active":true,"is_favorite":false,"tags":["docs","public"],"archived_at":null,"expires_at":null,"campaign_id":"22222222-2222-4222-8222-222222222222","campaign_name":"Launch","campaign_status":"active"}],"pagination":{"page_size":25,"has_more":false,"next_cursor":null}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}},"post":{"operationId":"post_links","summary":"Create a short link","description":"Creates a short link. If allow_duplicate is false and the destination already has an owned non-deleted link, the operation returns HTTP 200 with duplicate candidates and does not consume link quota; resubmit with allow_duplicate true to create another link. Required permission: links:write. Account quotas and ownership checks apply.","tags":["Links"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"links:write","x-required-permission":"links:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"destination_url":{"type":"string","format":"uri","maxLength":4096},"title":{"type":"string","maxLength":200},"expires_at":{"type":"string","format":"date-time","nullable":true},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":10},"namespace_id":{"type":"string","format":"uuid","nullable":true},"slug":{"type":"string","maxLength":64},"campaign_id":{"type":"string","format":"uuid","nullable":true},"allow_duplicate":{"type":"boolean","default":false}},"required":["destination_url"],"additionalProperties":false},"example":{"destination_url":"https://example.com/docs","title":"Documentation","tags":["docs"],"allow_duplicate":false}}}},"responses":{"200":{"description":"An existing-link duplicate check result; no link was created.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateLinkResponse"},"example":{"duplicate":true,"links":[{"id":"11111111-1111-4111-8111-111111111111","short_code":"aB3xY7kQ","destination_url":"https://example.com/docs","created_at":"2026-09-29T12:00:00.000Z","click_count":12,"is_active":true,"archived_at":null,"expires_at":null,"slug":null,"namespace_name":null,"canonical_path":null}]}}}},"201":{"description":"The newly created short link.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLinkResponse"},"example":{"link":{"id":"11111111-1111-4111-8111-111111111111","short_code":"aB3xY7kQ","namespace_id":null,"namespace_name":null,"slug":null,"canonical_path":null,"destination_url":"https://example.com/docs","created_at":"2026-09-29T12:00:00.000Z","title":"Documentation","is_active":true,"expires_at":null,"clerk_user_id":"user_example_123","campaign_id":null,"campaign_name":null,"campaign_status":null}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"409":{"description":"The request conflicts with the current resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"The resource cannot be changed in its current state."}}}},"413":{"description":"The JSON request body is larger than 32 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Request body is too large."}}}},"415":{"description":"The request body must use JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"unsupported_media_type","error":"Use Content-Type: application/json."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/links/{id}/tags":{"patch":{"operationId":"patch_links_id_tags","summary":"Replace link tags","description":"Replaces the complete tag list for a link. The submitted array is the new value, not an incremental add/remove operation. Required permission: links:write. Account quotas and ownership checks apply.","tags":["Links"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"links:write","x-required-permission":"links:write","parameters":[{"name":"id","in":"path","required":true,"description":"Owned resource UUID.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":10}},"required":["tags"],"additionalProperties":false},"example":{"tags":["docs","public"]}}}},"responses":{"200":{"description":"The link id and its replacement tags.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLinkTagsResponse"},"example":{"id":"11111111-1111-4111-8111-111111111111","tags":["docs","public"]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"413":{"description":"The JSON request body is larger than 32 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Request body is too large."}}}},"415":{"description":"The request body must use JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"unsupported_media_type","error":"Use Content-Type: application/json."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/links/{id}/campaign":{"put":{"operationId":"put_links_id_campaign","summary":"Assign or remove a link campaign","description":"Assigns a link to an active or scheduled campaign, or removes the assignment when campaign_id is null. Required permission: campaigns:write. Account quotas and ownership checks apply.","tags":["Links"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"campaigns:write","x-required-permission":"campaigns:write","parameters":[{"name":"id","in":"path","required":true,"description":"Owned resource UUID.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"campaign_id":{"type":"string","format":"uuid","nullable":true}},"required":["campaign_id"],"additionalProperties":false},"example":{"campaign_id":"22222222-2222-4222-8222-222222222222"}}}},"responses":{"200":{"description":"The link's resulting campaign assignment.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetLinkCampaignResponse"},"example":{"id":"11111111-1111-4111-8111-111111111111","campaign_id":"22222222-2222-4222-8222-222222222222","campaign_name":"Launch","campaign_status":"active"}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"409":{"description":"The request conflicts with the current resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"The resource cannot be changed in its current state."}}}},"413":{"description":"The JSON request body is larger than 32 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Request body is too large."}}}},"415":{"description":"The request body must use JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"unsupported_media_type","error":"Use Content-Type: application/json."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/campaigns":{"get":{"operationId":"get_campaigns","summary":"List campaigns","description":"Lists all campaigns owned by the account, newest first. Campaigns are available only when the account has an eligible plan. Required permission: campaigns:read. Account quotas and ownership checks apply.","tags":["Campaigns"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"campaigns:read","x-required-permission":"campaigns:read","parameters":[],"responses":{"200":{"description":"The account's campaigns.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignListResponse"},"example":{"campaigns":[{"id":"22222222-2222-4222-8222-222222222222","name":"Launch","description":"Documentation launch links","starts_at":"2026-09-29T00:00:00.000Z","ends_at":null,"archived_at":null,"tags":["launch"],"metadata":{"owner":"marketing"},"utm_parameters":{"utm_source":"newsletter","utm_medium":"email"},"created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z","status":"active","link_count":1}]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}},"post":{"operationId":"post_campaigns","summary":"Create a campaign","description":"Creates a campaign. Timestamp fields are ISO 8601 instants; the response normalizes them to UTC. Required permission: campaigns:write. Account quotas and ownership checks apply.","tags":["Campaigns"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"campaigns:write","x-required-permission":"campaigns:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":1000,"nullable":true},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time","nullable":true},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":10},"metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}]}},"utm_parameters":{"type":"object","properties":{"utm_source":{"type":"string","maxLength":200},"utm_medium":{"type":"string","maxLength":200},"utm_campaign":{"type":"string","maxLength":200},"utm_term":{"type":"string","maxLength":200},"utm_content":{"type":"string","maxLength":200}},"additionalProperties":false}},"required":["name"],"additionalProperties":false},"example":{"name":"Launch","description":"Documentation launch links","starts_at":"2026-09-29T00:00:00Z","ends_at":null,"tags":["launch"],"metadata":{"owner":"marketing"},"utm_parameters":{"utm_source":"newsletter","utm_medium":"email"}}}}},"responses":{"201":{"description":"The newly created campaign.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignResponse"},"example":{"campaign":{"id":"22222222-2222-4222-8222-222222222222","name":"Launch","description":"Documentation launch links","starts_at":"2026-09-29T00:00:00.000Z","ends_at":null,"archived_at":null,"tags":["launch"],"metadata":{"owner":"marketing"},"utm_parameters":{"utm_source":"newsletter","utm_medium":"email"},"created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z","status":"active","link_count":1}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"413":{"description":"The JSON request body is larger than 32 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Request body is too large."}}}},"415":{"description":"The request body must use JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"unsupported_media_type","error":"Use Content-Type: application/json."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/campaigns/{id}":{"put":{"operationId":"put_campaigns_id_","summary":"Replace campaign settings (send all desired settings)","description":"Replaces the campaign settings for the path id. Send every setting the campaign should retain. starts_at and ends_at are exact instants, including their supplied timezone offset, and are returned as normalized UTC timestamps. Required permission: campaigns:write. Account quotas and ownership checks apply.","tags":["Campaigns"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"campaigns:write","x-required-permission":"campaigns:write","parameters":[{"name":"id","in":"path","required":true,"description":"Owned resource UUID.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":1000,"nullable":true},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time","nullable":true},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":10},"metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}]}},"utm_parameters":{"type":"object","properties":{"utm_source":{"type":"string","maxLength":200},"utm_medium":{"type":"string","maxLength":200},"utm_campaign":{"type":"string","maxLength":200},"utm_term":{"type":"string","maxLength":200},"utm_content":{"type":"string","maxLength":200}},"additionalProperties":false}},"required":["name"],"additionalProperties":false},"example":{"name":"Launch","description":"Documentation launch links","starts_at":"2026-09-29T00:00:00-04:00","ends_at":null,"tags":["launch"],"metadata":{"owner":"marketing"},"utm_parameters":{"utm_source":"newsletter","utm_medium":"email"}}}}},"responses":{"200":{"description":"The replaced campaign.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignResponse"},"example":{"campaign":{"id":"22222222-2222-4222-8222-222222222222","name":"Launch","description":"Documentation launch links","starts_at":"2026-09-29T04:00:00.000Z","ends_at":null,"archived_at":null,"tags":["launch"],"metadata":{"owner":"marketing"},"utm_parameters":{"utm_source":"newsletter","utm_medium":"email"},"created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:05:00.000Z","status":"active","link_count":1}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"409":{"description":"The request conflicts with the current resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"The resource cannot be changed in its current state."}}}},"413":{"description":"The JSON request body is larger than 32 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Request body is too large."}}}},"415":{"description":"The request body must use JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"unsupported_media_type","error":"Use Content-Type: application/json."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/analytics":{"get":{"operationId":"get_analytics","summary":"Read aggregate analytics without raw visitor identifiers","description":"Returns a privacy-filtered analytics summary. Raw IP addresses, referrers, and user agents are omitted from this public response; only aggregate dimensions and popular links are returned. The report scans up to 20,000 newest events and sets truncated=true when that cap is reached. Analytics requests count toward the account limit of 15 per minute. Required permission: analytics:read. Account quotas and ownership checks apply.","tags":["Analytics"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"analytics:read","x-required-permission":"analytics:read","parameters":[{"name":"days","in":"query","required":false,"description":"Analytics window in calendar days.","schema":{"type":"integer","enum":[7,14,30,90,180],"default":30}},{"name":"campaign_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The compact analytics summary; it contains no raw visitor identifiers.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsSummaryResponse"},"example":{"scope":{"kind":"account"},"days":30,"range":{"start":"2026-08-30T12:00:00.000Z","end":"2026-09-29T12:00:00.000Z"},"total_clicks":42,"truncated":false,"sources":[{"label":"newsletter.example","count":24},{"label":"Direct","count":18}],"browsers":[{"label":"Chrome","count":30},{"label":"Safari","count":12}],"operating_systems":[{"label":"macOS","count":26},{"label":"Windows","count":16}],"time_of_day_utc":[{"label":"Afternoon","count":25},{"label":"Morning","count":17}],"popular_links":[{"link_id":"11111111-1111-4111-8111-111111111111","short_code":"aB3xY7kQ","namespace_name":null,"slug":null,"canonical_path":null,"destination_url":"https://example.com/docs","count":24}]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/campaigns/{id}/analytics":{"get":{"operationId":"get_campaigns_id_analytics","summary":"Read campaign analytics without raw visitor identifiers","description":"Returns campaign performance and aggregate audience dimensions without raw visitor identifiers. Click and hub-view collection each cap at 20,000 newest rows; truncated=true means one of those caps was reached. Analytics requests count toward the account limit of 15 per minute. Required permission: analytics:read. Account quotas and ownership checks apply.","tags":["Analytics"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"analytics:read","x-required-permission":"analytics:read","parameters":[{"name":"id","in":"path","required":true,"description":"Owned resource UUID.","schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","required":false,"description":"Analytics window in calendar days.","schema":{"type":"integer","enum":[7,14,30,90,180],"default":30}}],"responses":{"200":{"description":"The compact campaign analytics report; raw click and hub-view event arrays are intentionally omitted.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignAnalyticsResponse"},"example":{"campaign":{"id":"22222222-2222-4222-8222-222222222222","name":"Launch","description":"Documentation launch links","starts_at":"2026-09-29T00:00:00.000Z","ends_at":null,"archived_at":null,"tags":["launch"],"metadata":{"owner":"marketing"},"utm_parameters":{"utm_source":"newsletter","utm_medium":"email"},"created_at":"2026-09-29T12:00:00.000Z","updated_at":"2026-09-29T12:00:00.000Z","status":"active","link_count":1},"days":30,"range":{"start":"2026-08-30T12:00:00.000Z","end":"2026-09-29T12:00:00.000Z"},"total_clicks":42,"unique_visitors":35,"hub_views":{"total":18,"direct":14,"qr":4,"unique_visitors":16},"truncated":false,"mapped_links":[{"link_id":"11111111-1111-4111-8111-111111111111","short_code":"aB3xY7kQ","namespace_name":null,"slug":null,"canonical_path":null,"destination_url":"https://example.com/docs","count":42}],"top_links":[{"link_id":"11111111-1111-4111-8111-111111111111","short_code":"aB3xY7kQ","namespace_name":null,"slug":null,"canonical_path":null,"destination_url":"https://example.com/docs","count":42}],"sources":[{"label":"Direct","count":22},{"label":"newsletter.example","count":20}],"browsers":[{"label":"Chrome","count":30},{"label":"Safari","count":12}],"operating_systems":[{"label":"macOS","count":26},{"label":"Windows","count":16}]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/namespaces":{"get":{"operationId":"get_namespaces","summary":"List namespaces","description":"Lists namespaces and the account's current namespace capacity and editability flags. Required permission: namespaces:read. Account quotas and ownership checks apply.","tags":["Namespaces"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"namespaces:read","x-required-permission":"namespaces:read","parameters":[],"responses":{"200":{"description":"Namespace capacity and namespace records.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NamespaceListResponse"},"example":{"plan":"pro","limit":50,"used":1,"remaining":49,"namespaces":[{"id":"33333333-3333-4333-8333-333333333333","name":"go","created_at":"2026-09-29T12:00:00.000Z","link_count":4,"has_been_used":true,"can_use":true,"can_edit":false,"can_delete":false}]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}},"post":{"operationId":"post_namespaces","summary":"Create a namespace","description":"Creates a namespace under the account's current plan limit. Required permission: namespaces:write. Account quotas and ownership checks apply.","tags":["Namespaces"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"namespaces:write","x-required-permission":"namespaces:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":28}},"required":["name"],"additionalProperties":false},"example":{"name":"go"}}}},"responses":{"201":{"description":"The newly created namespace.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNamespaceResponse"},"example":{"namespace":{"id":"33333333-3333-4333-8333-333333333333","name":"go","created_at":"2026-09-29T12:00:00.000Z","link_count":0,"has_been_used":false,"can_edit":true,"can_delete":true}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"409":{"description":"The request conflicts with the current resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"The resource cannot be changed in its current state."}}}},"413":{"description":"The JSON request body is larger than 32 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Request body is too large."}}}},"415":{"description":"The request body must use JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"unsupported_media_type","error":"Use Content-Type: application/json."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/domain-mappings":{"get":{"operationId":"get_domain_mappings","summary":"List destination-domain mappings","description":"Lists destination-domain mappings and whether the current plan may manage them. Required permission: namespaces:read. Account quotas and ownership checks apply.","tags":["Namespaces"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"namespaces:read","x-required-permission":"namespaces:read","parameters":[],"responses":{"200":{"description":"Domain mapping records and plan capability.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainListResponse"},"example":{"plan":"pro","can_manage":true,"domains":[{"id":"44444444-4444-4444-8444-444444444444","namespace_id":"33333333-3333-4333-8333-333333333333","domain":"go.example.com","created_at":"2026-09-29T12:00:00.000Z"}]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}},"post":{"operationId":"post_domain_mappings","summary":"Set a destination-domain mapping","description":"Creates or reassigns a destination-domain mapping. Reusing an existing domain updates its namespace assignment and returns HTTP 200. Required permission: namespaces:write. Account quotas and ownership checks apply.","tags":["Namespaces"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"namespaces:write","x-required-permission":"namespaces:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"namespace_id":{"type":"string","format":"uuid"},"domain":{"type":"string","minLength":1,"maxLength":253}},"required":["namespace_id","domain"],"additionalProperties":false},"example":{"namespace_id":"33333333-3333-4333-8333-333333333333","domain":"go.example.com"}}}},"responses":{"200":{"description":"The resulting domain mapping.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainResponse"},"example":{"domain":{"id":"44444444-4444-4444-8444-444444444444","namespace_id":"33333333-3333-4333-8333-333333333333","domain":"go.example.com","created_at":"2026-09-29T12:00:00.000Z"}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"413":{"description":"The JSON request body is larger than 32 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Request body is too large."}}}},"415":{"description":"The request body must use JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"unsupported_media_type","error":"Use Content-Type: application/json."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/domain-mappings/{id}":{"delete":{"operationId":"delete_domain_mappings_id_","summary":"Remove a destination-domain mapping","description":"Removes an owned destination-domain mapping. Required permission: namespaces:write. Account quotas and ownership checks apply.","tags":["Namespaces"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"namespaces:write","x-required-permission":"namespaces:write","parameters":[{"name":"id","in":"path","required":true,"description":"Owned resource UUID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The deleted mapping id.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResponse"},"example":{"id":"44444444-4444-4444-8444-444444444444","deleted":true}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/smart-paste-sites":{"get":{"operationId":"get_smart_paste_sites","summary":"List personal Smart Paste sites","description":"Lists personal Smart Paste sites and whether the current plan may manage them. Smart Paste sites are not available for Teams workspace API keys. Required permission: smart_paste:read. Account quotas and ownership checks apply.","tags":["Smart Paste"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"smart_paste:read","x-required-permission":"smart_paste:read","parameters":[],"responses":{"200":{"description":"Smart Paste capability and site records.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartPasteListResponse"},"example":{"plan":"pro","can_manage":true,"domains":[{"id":"44444444-4444-4444-8444-444444444444","domain":"docs.example.com","created_at":"2026-09-29T12:00:00.000Z"}]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}},"post":{"operationId":"post_smart_paste_sites","summary":"Enable a personal Smart Paste site","description":"Enables Smart Paste for a personal site. Re-adding an existing site is idempotent and returns its current record. Required permission: smart_paste:write. Account quotas and ownership checks apply.","tags":["Smart Paste"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"smart_paste:write","x-required-permission":"smart_paste:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":253}},"required":["domain"],"additionalProperties":false},"example":{"domain":"docs.example.com"}}}},"responses":{"200":{"description":"The resulting Smart Paste site.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartPasteResponse"},"example":{"domain":{"id":"44444444-4444-4444-8444-444444444444","domain":"docs.example.com","created_at":"2026-09-29T12:00:00.000Z"}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"413":{"description":"The JSON request body is larger than 32 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Request body is too large."}}}},"415":{"description":"The request body must use JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"unsupported_media_type","error":"Use Content-Type: application/json."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}},"/smart-paste-sites/{id}":{"delete":{"operationId":"delete_smart_paste_sites_id_","summary":"Disable a personal Smart Paste site","description":"Disables Smart Paste for an owned personal site. Required permission: smart_paste:write. Account quotas and ownership checks apply.","tags":["Smart Paste"],"security":[{"ApiKey":[]}],"x-simpurl-scope":"smart_paste:write","x-required-permission":"smart_paste:write","parameters":[{"name":"id","in":"path","required":true,"description":"Owned resource UUID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The deleted Smart Paste site id.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResponse"},"example":{"id":"44444444-4444-4444-8444-444444444444","deleted":true}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_request","error":"Invalid request."}}}},"401":{"description":"The API key is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"invalid_api_key","error":"The API key is invalid, expired, or revoked."}}}},"403":{"description":"The key lacks the required permission or the account plan cannot use this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"insufficient_scope","error":"This operation requires the documented permission."}}}},"404":{"description":"The requested resource is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Resource not found."}}}},"429":{"description":"The account API rate limit was reached: 100 requests per UTC clock hour, shared across all keys for the account or Teams workspace. Additional burst limits are 30 writes and 15 analytics requests per minute. X-RateLimit headers describe the hourly allowance; Retry-After describes when retrying is possible.","headers":{"X-RateLimit-Limit":{"description":"Account-wide requests allowed per UTC clock hour, shared across all external API keys.","schema":{"type":"integer","enum":[100],"example":100}},"X-RateLimit-Remaining":{"description":"Hourly requests remaining after this request. Authorized requests count even if validation or a burst limit rejects them.","schema":{"type":"integer","minimum":0,"maximum":100,"example":99}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds for the next UTC hour boundary.","schema":{"type":"integer","example":1800000000}},"Retry-After":{"description":"Seconds until the applicable hourly or burst limit resets. Honor the actual response value; it is not always 60.","schema":{"type":"integer","minimum":1,"maximum":3600,"example":1800}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"rate_limited","error":"The account's 100-request hourly API limit was reached. Retry after 1800 seconds."}}}},"500":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}},"503":{"description":"The API could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"service_unavailable","error":"SimpURL could not complete this request. Please try again."}}}}}}}}}