# Hoko Documentation > Developer guides and API reference sourced from the docs pages. ## Navigation ### Getting Started - [Introduction](https://docs.hoko.to/introduction) - [API Keys](https://docs.hoko.to/api-keys) - [Authentication](https://docs.hoko.to/authentication) - [Rate Limits](https://docs.hoko.to/rate-limits) - [Errors](https://docs.hoko.to/errors) ### Developer tools - [Hoko CLI](https://docs.hoko.to/cli) ### Links - [Introduction](https://docs.hoko.to/links/introduction) - [(GET) Get links](https://docs.hoko.to/links/get) - [(POST) Create links](https://docs.hoko.to/links/post) - [(PUT) Update/Upsert links](https://docs.hoko.to/links/put) - [(DELETE) Delete links](https://docs.hoko.to/links/delete) ### Collections - [Introduction](https://docs.hoko.to/collections/introduction) - [(GET) Get collections](https://docs.hoko.to/collections/get) - [(POST) Create collections](https://docs.hoko.to/collections/post) - [(PUT) Update/Upsert collections](https://docs.hoko.to/collections/put) - [(DELETE) Delete collections](https://docs.hoko.to/collections/delete) ### Developers - [Custom API clients](https://docs.hoko.to/custom-api) ### Tags - [Introduction](https://docs.hoko.to/tags/introduction) - [(GET) Get tags](https://docs.hoko.to/tags/get) - [(POST) Create tags](https://docs.hoko.to/tags/post) - [(PUT) Update/Upsert tags](https://docs.hoko.to/tags/put) - [(DELETE) Delete tags](https://docs.hoko.to/tags/delete) ### Analytics - [Introduction](https://docs.hoko.to/analytics/introduction) - [(GET) Get analytics](https://docs.hoko.to/analytics/get) ### Integrations - [Connected apps](https://docs.hoko.to/integrations/apps) - [Automation recipes](https://docs.hoko.to/integrations/automation) - [Receive link.created webhooks](https://docs.hoko.to/integrations/link-created) - [Google Tag Manager attribution template](https://docs.hoko.to/integrations/google-tag-manager) - [Power Automate](https://docs.hoko.to/integrations/power-platform) - [Zapier](https://docs.hoko.to/integrations/zapier) - [Make](https://docs.hoko.to/integrations/make) - [n8n](https://docs.hoko.to/integrations/n8n) - [Commerce integrations](https://docs.hoko.to/integrations/commerce) - [Social and CMS integrations](https://docs.hoko.to/integrations/social-cms) - [Reporting integrations](https://docs.hoko.to/integrations/reporting) - [OAuth provider connections](https://docs.hoko.to/integrations/oauth) - [Later and Hootsuite](https://docs.hoko.to/integrations/later-hootsuite) ### Customers - [Introduction](https://docs.hoko.to/customers/introduction) - [(GET) Get customers](https://docs.hoko.to/customers/get) - [(PUT) Update customers](https://docs.hoko.to/customers/put) - [(DELETE) Delete customers](https://docs.hoko.to/customers/delete) ### Partners - [Introduction](https://docs.hoko.to/partners/introduction) - [(GET) Get partners](https://docs.hoko.to/partners/get) - [(POST) Create partners](https://docs.hoko.to/partners/post) - [(PUT) Update/Upsert partners](https://docs.hoko.to/partners/put) - [(DELETE) Delete partners](https://docs.hoko.to/partners/delete) ### Conversion Tracking - [Introduction](https://docs.hoko.to/track/introduction) - [Browser attribution script (analytics.js)](https://docs.hoko.to/track/analytics-js) - [Embedded click tracking](https://docs.hoko.to/track/embedded-click) - [Track lead events](https://docs.hoko.to/track/lead) - [Track sale events](https://docs.hoko.to/track/sale) ### Webhooks - [Introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Workspace](https://docs.hoko.to/webhooks/workspace) - [API key](https://docs.hoko.to/webhooks/api-key) - [Link](https://docs.hoko.to/webhooks/link) - [Tag](https://docs.hoko.to/webhooks/tag) - [Partner](https://docs.hoko.to/webhooks/partner) - [UTM template](https://docs.hoko.to/webhooks/utm-template) - [Collection](https://docs.hoko.to/webhooks/collection) - [Member profile](https://docs.hoko.to/webhooks/member-profile) - [Invitation](https://docs.hoko.to/webhooks/invitation) - [Invoice](https://docs.hoko.to/webhooks/invoice) - [Subscription](https://docs.hoko.to/webhooks/subscription) - [Webhook](https://docs.hoko.to/webhooks/webhook) - [Customer](https://docs.hoko.to/webhooks/customer) - [Lead](https://docs.hoko.to/webhooks/lead) - [Sale](https://docs.hoko.to/webhooks/sale) ### Logs - [Introduction](https://docs.hoko.to/logs/introduction) ## Documentation Pages ### Introduction Hoko is a modern link attribution platform that empowers you to create branded short links, track conversions end-to-end, and measure marketing performance with precision. Docs URL: https://docs.hoko.to/introduction Markdown: https://docs.hoko.to/introduction/README.md ## What is Hoko? Hoko is a comprehensive link attribution and conversion tracking platform designed for modern marketing teams. Whether you're running multi-channel campaigns, tracking affiliate performance, or measuring ROI, Hoko provides the tools you need to understand exactly how your marketing efforts drive results. Built with developers in mind, Hoko offers a REST API for automated link management, click analytics, and lead or sale tracking workflows. Conversion reporting requires the integration to send those events and remains subject to current plan and rollout availability. The public OpenAPI document is the detailed wire contract for Developer API schemas, status codes, and generated clients. The SST remains the high-level canonical product and API baseline. ## Resource identifiers Canonical API requests and responses use bare 26-character Crockford ULIDs. Documentation examples use typed placeholders such as ``; replace them with actual public IDs when making requests. Storage identifiers are not returned in public API payloads. ## Key Features Hoko combines powerful link management with advanced analytics and conversion tracking. Here's what makes it special: - Managed Short Links - Create memorable short URLs on hoko.to with readable custom slugs - Link Analytics - Review clicks, referrers, UTM values, device/browser context, and location context - Conversion Tracking - Connect clicks to leads and sales with flexible event tracking and customer attribution - REST API - Programmatic access through the documented endpoints for automation and integrations. Webhook management and activity logs are also available through the documented API with the required permissions. - Multi-Channel Attribution - Track performance across campaigns, partners, and channels with granular UTM parameter support - Partner Management - Organize and track affiliate partners with commission and performance analytics - Collections & Tags - Organize links efficiently with collections and tags for better campaign management - Customer Insights - Build comprehensive customer profiles by tracking their journey from click to conversion ## Use Cases Hoko is perfect for a wide range of marketing and attribution scenarios: - Marketing Campaigns - Track performance of email, social media, and paid advertising campaigns - Affiliate Programs - Manage partner links and track commission-based conversions - E-commerce Attribution - Connect marketing touchpoints to actual sales and revenue - Lead Generation - Track which channels and campaigns generate the highest-quality leads - Content Marketing - Measure the impact of blog posts, newsletters, and content shares - Multi-Tenant SaaS - Track links and conversions across different customer segments or tenants - API Integrations - Build custom integrations with CRM, marketing automation, and analytics tools ## Getting Started Ready to get started? Here's a quick overview of what you'll need: - Create a Hoko account and set up your workspace - Create your first collection to organize links - Generate an API key with appropriate scopes for your use case - Start creating links via the dashboard or API - Track conversions by integrating the conversion tracking endpoints > **Tip: Pro Tip** > Start with the Links section to understand how to create and manage short links, then explore Analytics to see how to track performance, and finally dive into Conversion Tracking to connect clicks to business outcomes. --- ### API Keys Create and manage API keys with granular permission scopes. Secure your integrations with the principle of least privilege. Docs URL: https://docs.hoko.to/api-keys Markdown: https://docs.hoko.to/api-keys/README.md ## Overview API keys are one supported credential for Hoko API requests. You can also use a human token, an OAuth access token, or an authenticated browser session. Each API key is associated with your workspace and can be configured with specific permission scopes. This granular access control enables you to create different keys for different purposes—for example, a read-only key for analytics dashboards, or a write key for automated link creation scripts. ## Creating API Keys Create new API keys from your workspace dashboard under Settings > Integrations > API Keys. When creating a key, you'll need to: 1. Provide a descriptive name to help you identify the key's purpose 2. Select the appropriate permission scopes based on what operations the key needs to perform 3. Copy the key immediately after creation—it will only be displayed once for security reasons > **Warning: Important Security Notice** > API keys are displayed only once during creation. If you lose a key, you must revoke it and create a new one. Never share API keys publicly or commit them to version control. ## Permission Scopes Scopes define what operations an API key can perform. By granting only the minimum required permissions, you follow security best practices and limit potential damage if a key is compromised. Each scope is independent—you can combine multiple scopes to create keys with exactly the permissions you need. - linksRead - Read and list links (GET /links) - linksWrite - Create, update, and delete links (POST, PUT, DELETE /links) - collectionsRead - Read and list collections (GET /collections) - collectionsWrite - Create, update, and delete collections (POST, PUT, DELETE /collections) - tagsRead - Read and list tags (GET /tags) - tagsWrite - Create, update, and delete tags (POST, PUT, DELETE /tags) - analyticsRead - Access click analytics and performance data (GET /analytics) - conversionsWrite - Track lead and sale conversion events (POST /track/lead, POST /track/sale) - customersRead - Read customer data (GET /customers) - customersWrite - Update and delete customer data (PUT, DELETE /customers) - partnersRead - Read partner data (GET /partners) - partnersWrite - Create, update, and delete partners (POST, PUT, DELETE /partners) > **Tip: Best Practice** > Create separate API keys for different environments (development, staging, production) and different use cases (read-only monitoring, automated link creation, conversion tracking). This makes it easier to rotate keys and audit access. ## Using API Keys Use one credential on each request. The API validates the credential and checks the scopes required by the operation. **Header Format** ```text Authorization: Bearer ``` You can send an API key in the alternate header: ```text X-API-Key: ``` For a human token or OAuth access token, replace `` with the access token. First-party browser requests may use the authenticated session cookie. **curl Example** ```bash curl -X GET "https://api.hoko.to/links" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` ## Revoking API Keys You can revoke API keys at any time from your workspace settings. Revocation is immediate and permanent—revoked keys cannot be restored or reactivated. Revoke keys immediately if you suspect they've been compromised, or when they're no longer needed. This is a critical security practice, especially when keys are used in production environments. > **Error: Security Alert** > If an API key is exposed or compromised, revoke it immediately and create a new one. Monitor your API usage logs for any suspicious activity after key revocation. --- ### Authentication Secure Hoko requests with an authorized credential: an API key, human token, OAuth access token, or authenticated browser session. Docs URL: https://docs.hoko.to/authentication Markdown: https://docs.hoko.to/authentication/README.md ## Overview Hoko authorizes requests through the credential available to the client. Supported authorized access includes an API key, human token, OAuth access token, or authenticated browser session. The client surface and operation determine which credential is appropriate. API and MCP clients send an access credential in the Authorization header. Browser requests use the authenticated session cookie. The CLI can use browser OAuth for a human account or an API key for automation. Human Tokens are limited to personal Apps connection reads and removal; they do not authorize workspace operations. See [API keys](https://docs.hoko.to/api-keys) for key creation and scope selection. ## Bearer Token Authentication Use an API key when a server-side integration, script, or automation job needs scoped workspace access. Include the key in each request using the Authorization header with the Bearer scheme. The API key should be placed immediately after "Bearer " (note the space). Both the full format `Bearer ` and just the API key itself are accepted for convenience. **Header Format** ```text Authorization: Bearer ``` **curl Example** ```bash curl -X GET "https://api.hoko.to/links" \ -H "Authorization: Bearer " ``` **JavaScript (fetch)** ```javascript fetch('https://api.hoko.to/links', { headers: { "Authorization": "Bearer ", "Content-Type": "application/json" } }) ``` **Python (requests)** ```python import requests headers = { 'Authorization': 'Bearer ', 'Content-Type': 'application/json' } response = requests.get('https://api.hoko.to/links', headers=headers) ``` > **Warning: Security Best Practice** > Never expose your API keys in client-side code, public repositories, or shared documents. Always store API keys securely using environment variables or secret management services. ## Authentication Errors When authentication fails, the API returns a 401 Unauthorized status code with a descriptive error message. The exact message identifies the credential or session problem; do not retry with a different credential until its intended client surface and operation are confirmed. - Missing credential - The request does not include an accepted credential or authenticated session. - Invalid credential - The supplied credential is malformed, revoked, expired, or not valid for the target workspace. **Error Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` > **Info: Troubleshooting** > Check the client surface, credential source, workspace, operation, and required scopes. For an API key, verify that it is active and included in the Authorization header. For browser access, sign in again if the session has expired. --- ### Rate Limits Understand rate limits, monitor your usage, and implement proper retry logic to ensure reliable API access. Docs URL: https://docs.hoko.to/rate-limits Markdown: https://docs.hoko.to/rate-limits/README.md ## Overview Rate limiting protects the API from abuse and ensures fair usage across all workspaces. All API requests are rate limited per workspace based on your subscription plan. Rate limits are applied using a sliding window algorithm per minute. This means requests are counted within a rolling 60-second window, providing smooth and predictable rate limiting behavior. Each plan tier has different rate limits to accommodate various usage patterns, from small projects to enterprise-scale operations. > **Info: Rate Limit Scope** > Rate limits are applied per workspace, not per API key. All API keys within the same workspace share the same rate limit pool. ## Rate Limit Headers Every authenticated API response after the workspace is identified includes rate limit information in HTTP headers, allowing you to monitor your usage and implement intelligent retry logic. Requests that fail before a valid API key resolves to a workspace may not include workspace-specific rate limit headers. Use these headers to build rate limit-aware applications that can proactively manage their API usage. - X-RateLimit-Limit - The maximum number of requests allowed per minute for your plan tier - X-RateLimit-Remaining - The number of requests remaining in the current window - X-RateLimit-Reset - Unix timestamp (in seconds) indicating when the current rate limit window resets **Response Headers** ```text // Example response headers X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 987 X-RateLimit-Reset: 1704067200 ``` > **Tip: Implementation Tip** > Monitor the X-RateLimit-Remaining header and implement exponential backoff when it approaches zero. This prevents hitting rate limits and ensures smooth API usage. ## Handling Rate Limit Exceeded When you exceed your rate limit: - The API returns a 429 Too Many Requests status code. - The response includes detailed information to help you implement proper retry logic. - The retryAfter field indicates the number of seconds to wait before retrying. - Its value is calculated from when the current rate limit window resets. **429 Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 45 } ``` > **Warning: Best Practice** > Always respect the retryAfter value and implement exponential backoff. Avoid aggressive retry loops that could further impact your rate limit. Consider implementing request queuing for high-volume scenarios. ## Best Practices To maximize API reliability and avoid rate limit issues, follow these best practices: - Monitor rate limit headers when present to track your usage - Implement exponential backoff when approaching rate limits - Use batch endpoints when available to reduce the number of requests - Cache responses when appropriate to minimize API calls - Consider upgrading your plan if you consistently approach rate limits - Implement request queuing for high-volume operations - Use webhooks for real-time updates instead of polling when possible --- ### Errors Understand error responses, status codes, and how to handle API errors gracefully in your applications. Docs URL: https://docs.hoko.to/errors Markdown: https://docs.hoko.to/errors/README.md ## Overview The Hoko API uses standard HTTP status codes to indicate the result of API requests. All error responses follow a consistent, predictable format that makes error handling straightforward in your applications. Error messages are provided in both English and Arabic, allowing you to display user-friendly error messages regardless of your application's language preference. Understanding error responses helps you build robust integrations that gracefully handle edge cases and provide clear feedback to users. Successful responses use 2xx HTTP status codes and return the raw documented payload for the endpoint, such as an array of links or an object with `deletedIds`. Failure responses use non-2xx HTTP status codes and include an `error` object. Do not infer success or failure from the presence of `data` or `message` fields. Unknown object properties in request bodies are ignored by runtime validation. ## HTTP Status Codes The API uses standard HTTP status codes to communicate request outcomes. Familiarize yourself with these codes to implement proper error handling: - 400 Bad Request - The request is malformed, contains invalid parameters, or violates API constraints. Check your request format and parameters. - 401 Unauthorized - Authentication failed. The API key is missing, invalid, expired, or revoked. Verify your API key is correct and active. - 403 Forbidden - The API key is valid but lacks the required permission scopes for this operation. Check the missingScopes field in the response. - 404 Not Found - Returned for unknown endpoints. Resource validation errors are reported as 400 Bad Request. - 429 Too Many Requests - Rate limit exceeded. Wait for the retryAfter period before making additional requests. - 500 Internal Server Error - An unexpected server error occurred. These are rare; if you encounter this, contact support with request details. > **Info: Error Handling Strategy** > Implement comprehensive error handling that checks status codes and displays appropriate messages to users. For 4xx errors, the issue is typically with the request. For 5xx errors, retry with exponential backoff. ## Error Response Format All error responses follow a consistent structure. The error object contains bilingual messages, and additional fields provide context-specific information depending on the error type. **Error Format** ```json { "error": { "en": "Error message in English", "ar": "رسالة خطأ بالعربية" }, "missingScopes": ["linksWrite"], // Only for 403 errors "retryAfter": 45 // Only for 429 errors } ``` > **Tip: Error Message Selection** > Use the appropriate language field (en or ar) from the error object based on your application's language preference or user settings. ## Error Examples Here are examples of common error responses you might encounter: **400 Bad Request** ```json { "error": { "en": "Invalid request format", "ar": "تنسيق طلب غير صالح" } } ``` **401 Unauthorized** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` **403 Forbidden** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["linksWrite", "collectionsWrite"] } ``` **429 Too Many Requests** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 45 } ``` --- ### Hoko CLI Command syntax, authentication inputs, output, and exit codes for the Hoko CLI. Docs URL: https://docs.hoko.to/cli Markdown: https://docs.hoko.to/cli/README.md ## Install Use the [CLI Help guide](https://help.hoko.to/cli) for installation and first-run steps. This reference keeps the command and machine-readable contract. ## Authenticate Use the [CLI Help guide](https://help.hoko.to/cli) for browser sign-in and workspace selection. API-key and human-token environment usage is documented below for automation. ## Transport migration CLI 0.1.0 retires the old `/operations/` HTTP transport. `hoko operations list` and `hoko operations describe ` are local discovery commands; resource commands use the direct REST binding documented for each resource. Update scripts that post to `/operations/...` before upgrading. The CLI does not auto-update. ## Run commands Resource commands print JSON to stdout. Errors print JSON to stderr and return a non-zero exit code. ```bash hoko links list hoko links create --url https://example.com --collection-id hoko analytics list --take 50 hoko webhooks list ``` Resources include `links`, `collections`, `tags`, `partners`, `utm-templates`, `customers`, `analytics`, `events`, `journeys`, `webhooks`, `usage`, `keys`, `lead`, and `sale`. Use the generic operation command for named engine operations: ```bash hoko operations list hoko operations describe measurement.events.list ``` **Input, output, and environment** Commands accept JSON with `--body JSON`, `--body @file.json`, or `--body -` for stdin. JSON is written to stdout by default; `--output table` selects a human-readable table and `--json` forces JSON. Structured errors are written to stderr. Global deployment flags are `--api ` and `--issuer `. `HOKO_API_KEY` authenticates automation, `HOKO_AUTH_TOKEN` supplies a human token, `HOKO_API_URL` and `HOKO_AUTH_URL` select origins, and `HOKO_API_RESOURCE` selects the resource. Do not combine `HOKO_AUTH_TOKEN` with `HOKO_API_KEY` or stored OAuth credentials. ## Exit codes | Code | Meaning | | ---- | ---------------------------------------------------------------------- | | `0` | Success. | | `1` | Unexpected local failure. | | `2` | Invalid command, input, or request. | | `3` | Missing or invalid credentials, HTTP 401, or credential-store failure. | | `4` | Authorization denied (HTTP 403). | | `5` | Rate limit reached (HTTP 429). | | `6` | Network or connection failure. | | `7` | Server failure (HTTP 5xx) or invalid discovery response. | ## Use another deployment Pass both origins when you work against staging or local development: ```bash hoko --api https://api.staging.hoko.to --issuer https://auth.staging.hoko.to auth login ``` For local Portless development, use HTTP loopback origins: ```bash hoko --api http://api.hoko.localhost:1355 --issuer http://auth.hoko.localhost:1355 auth login ``` The values must be origins. Do not include a path, query string, fragment, username, or password. ## Related references - [API authentication](https://docs.hoko.to/authentication) - [API rate limits](https://docs.hoko.to/rate-limits) - [OpenAPI document](https://api.hoko.to/openapi.json) - [CLI machine-readable summary](https://cli.hoko.to/llms.txt) - [Full CLI command reference](https://cli.hoko.to/llms-full.txt) --- ### Introduction The Links API is the foundation of Hoko, enabling you to create, manage, and track short links programmatically. Docs URL: https://docs.hoko.to/links/introduction Markdown: https://docs.hoko.to/links/introduction/README.md ## Overview Links are the core building blocks of Hoko. Every short link you create becomes a trackable touchpoint that connects your marketing efforts to business outcomes. The Links API provides full CRUD operations (Create, Read, Update, Delete) for managing your link library. Create branded short URLs, organize them with collections and existing tag IDs, attach UTM parameters for campaign tracking, and leverage partner attribution for affiliate programs. Each link automatically generates a unique short ID and branded short URL, making it easy to share and track across all your marketing channels. Links support rich metadata including titles, descriptions, images, and custom external IDs for seamless integration with your existing systems. - (GET) Retrieve links with flexible filtering by ID, external ID, tenant, or partner - (POST) Create one or more links with rich metadata, UTM parameters, and existing tag IDs - (PUT) Update existing links or create new ones with upsert operations - (DELETE) Soft delete links while preserving historical analytics data > **Tip: Getting Started** > Before creating links, ensure you have at least one collection in your workspace. Every link must belong to a collection for organization. Use externalId to maintain references to links in your own system for seamless synchronization. --- ### (GET) Get links Retrieve links from your workspace with flexible filtering options. Filter by link ID, external ID, tenant ID, or partner ID. Docs URL: https://docs.hoko.to/links/get Markdown: https://docs.hoko.to/links/get/README.md ## Endpoint GET /links Retrieve links from your workspace with flexible filtering options. Filter by link ID, external ID, tenant ID, or partner ID to find exactly what you need. The endpoint supports efficient pagination and sorting, making it easy to browse large link libraries. Results are returned as an array of link objects, each containing complete link information including the generated short URL, QR code URL, collection ID, and assigned tag IDs. **Endpoint** ```text GET /links ``` ## Authentication Requires an authorized credential with permission for `linksRead`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Query Parameters All parameters are optional. Use them to filter and paginate results. | Parameter | Type | Required | Location | Description | | ---------- | ------------- | -------- | -------- | ------------------------------------------------------------------------------------------- | | id | string (ULID) | No | query | Filter by specific link ID. Returns a single link if found. | | externalId | string | No | query | Filter by external ID. Useful for syncing with external systems. | | tenantId | string | No | query | Filter by tenant ID for multi-tenant scenarios. | | partnerId | string (ULID) | No | query | Filter by partner ID to retrieve all links associated with a specific partner. | | take | number | No | query | Number of results to return (default: 50, min: 1, max: 5,000). | | skip | number | No | query | Number of results to skip for pagination (default: 0, min: 0). | | sort | string | No | query | Sort order by createdAt: "asc" for oldest first, "desc" for newest first (default: "desc"). | > **Warning: Request Limits** > The `take` parameter supports values from 1 to 5,000. Requests above 5,000 are rejected. ## Status Codes ### 200 Successfully retrieved links. **Request** ```bash curl -X GET "https://api.hoko.to/links?take=50&sort=desc" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links?take=50&sort=desc', { method: 'GET', headers: { Authorization: 'Bearer ' } }); const links = await response.json(); ``` **Response** ```json [ { "id": "", "url": "https://example.com", "shortUrl": "https://hoko.to/abc123", "qrCode": "https://hoko.to/qrcode?text=https%3A%2F%2Fhoko.to%2Fabc123%3Fqr%3D1&size=512&errorCorrection=H&foreground=000000&background=FFFFFF&margin=1&format=svg", "title": "Example Link", "description": "An example link", "image": "https://example.com/image.jpg", "utm": null, "expiresAt": null, "expiredUrl": null, "password": null, "cloaked": false, "ios": null, "android": null, "geo": null, "collectionId": "", "tagIds": [""], "externalId": null, "tenantId": null, "partnerId": null, "createdAt": "2024-01-01T00:00:00Z" } ] ``` ### 400 Invalid query parameters. This includes invalid ULID filters or invalid `take`, `skip`, or `sort` values. **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X GET "https://api.hoko.to/links" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'GET', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required linksRead scope. **Request** ```bash curl -X GET "https://api.hoko.to/links" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'GET', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["linksRead"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X GET "https://api.hoko.to/links" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'GET', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples Here are practical examples of retrieving links: **Request** ```bash curl -X GET "https://api.hoko.to/links?take=50&sort=desc" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links?take=50&sort=desc', { method: 'GET', headers: { Authorization: 'Bearer ' } }); const links = await response.json(); ``` **Response** ```json [ { "id": "", "url": "https://example.com", "shortUrl": "https://hoko.to/abc123", "qrCode": "https://hoko.to/qrcode?text=https%3A%2F%2Fhoko.to%2Fabc123%3Fqr%3D1&size=512&errorCorrection=H&foreground=000000&background=FFFFFF&margin=1&format=svg", "title": "Example Link", "description": "An example link", "image": "https://example.com/image.jpg", "utm": { "source": "google", "medium": "cpc", "campaign": "summer", "term": "keyword", "content": "ad_content" }, "expiresAt": null, "expiredUrl": null, "password": null, "cloaked": false, "ios": null, "android": null, "geo": null, "collectionId": "", "tagIds": [""], "externalId": "ext_123", "tenantId": "tenant_123", "partnerId": "", "createdAt": "2024-01-01T00:00:00Z" } ] ``` > **Info: Filtering Tips** > You can combine multiple filters (id, externalId, tenantId, partnerId) in a single request. When multiple filters are provided, results match any of the specified filters. Use pagination (take/skip) to efficiently browse large result sets. --- ### (POST) Create links Create one or more links in a single request. Each link requires a destination URL and collection ID. Docs URL: https://docs.hoko.to/links/post Markdown: https://docs.hoko.to/links/post/README.md ## Endpoint POST /links Create one or more links in a single request. This endpoint accepts an array of link objects, allowing you to create multiple links efficiently in one API call. Each link requires a destination URL and a collection ID. A unique short ID is automatically generated for each link, producing a short URL and QR code URL under https://hoko.to. You can include rich metadata such as titles, descriptions, images, UTM parameters, tag IDs, and custom external IDs to organize and track your links effectively. **Endpoint** ```text POST /links ``` ## Authentication Requires an authorized credential with permission for `linksWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body The request body must be an array of link objects. Each object represents one link to create. You can create up to 10,000 links in a single request. However, the actual maximum may be lower based on your subscription plan limits and available resources. | Parameter | Type | Required | Location | Description | | ------------ | ------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | url | string (URL) | Yes | body | The destination URL that the short link will redirect to. Must be a valid HTTPS URL. | | collectionId | string (ULID) | Yes | body | The ID of the collection (folder) to organize this link. The collection must exist in your workspace. | | tagIds | string[] | No | body | Existing tag IDs to assign to this link. Every tag must already exist in your workspace. | | title | string | No | body | A descriptive title for the link. Useful for organization and identification. | | description | string | No | body | Additional description or notes about the link. | | image | string (URL) | No | body | A preview image URL for the link. Must be a valid HTTPS URL. | | utm | object | No | body | UTM parameters for campaign tracking. Create requests accept string values for source, medium, campaign, term, content, and referral. | | expiresAt | string | No | body | ISO date-time when the link should expire. Requires a plan with link expiration. | | expiredUrl | string (URL) | No | body | Destination used after expiration. Requires a plan with link expiration. | | password | string | No | body | Password required before resolving the destination. Requires a plan with password protection. | | cloaked | boolean | No | body | Render the resolved destination in an iframe. The destination is preflighted and rejected with 400 if it currently blocks iframe rendering. Requires a plan with link cloaking. | | ios | string (URL) | No | body | Destination for iOS visitors. Requires a plan with device targeting. | | android | string (URL) | No | body | Destination for Android visitors. Requires a plan with device targeting. | | geo | object/null | No | body | Country-code destination map such as `{ "SA": "https://example.com/sa" }`; send null or omit for no geo targeting. Requires geo targeting when set. | | externalId | string | No | body | A custom external ID for syncing with external systems. Must be unique within your workspace. | | tenantId | string | No | body | A tenant identifier for multi-tenant scenarios. Useful for segmenting links by customer or organization. | | partnerId | string (ULID) | No | body | The ID of the partner associated with this link. Used for affiliate and partner attribution tracking. | > **Warning: Plan Limits** > The actual maximum number of links you can create per request may be lower than 10,000 based on your subscription plan limits and available resources. The system will enforce both the hard limit (10,000) and your plan-specific limits. ## Advanced Link Behavior Advanced fields are applied only when they are set on the link and your workspace plan supports the feature. All URL fields accepted by this endpoint must use `https:`. This includes `url`, `image`, `expiredUrl`, `ios`, `android`, and every URL value in `geo`. - `password`: Visitors must enter the password before Hoko resolves the final destination. A correct password stores a secure, HTTP-only cookie scoped to that short link, so the same visitor can continue without re-entering it. - `expiresAt`: Use an ISO date-time with timezone offset, such as `2026-12-31T23:59:00Z`. When the current server time is later than `expiresAt`, the link is expired. If `expiredUrl` is set, Hoko sends visitors there. If it is not set, Hoko shows an expired-link page. - `ios` and `android`: Device destinations are selected from the visitor's User-Agent. iOS and Android checks run before geo targeting. - `geo`: Map ISO 3166-1 alpha-2 country codes to destination URLs, for example `{ "SA": "https://example.com/sa" }`. Use uppercase country codes. Send `null` or omit the field for no geo targeting. Country detection is best-effort and uses trusted edge country headers when available, then IP lookup. - `cloaked`: Hoko renders the resolved destination in a full-page iframe. Create requests preflight the destination and return 400 if it currently blocks iframe rendering. Resolution order is: password gate, expiration, iOS/Android targeting, geo targeting, default `url`, then cloaking. Expired links do not run device or geo targeting. ## Status Codes ### 201 Links created successfully. **Request** ```bash curl -X POST "https://api.hoko.to/links" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "url": "https://example.com", "collectionId": "", "tagIds": [""], "expiresAt": "2026-12-31T23:59:00Z", "expiredUrl": "https://example.com/expired", "password": "launch", "cloaked": true, "ios": "https://example.com/ios", "android": "https://example.com/android", "geo": { "SA": "https://example.com/sa" } } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { url: 'https://example.com', collectionId: '', tagIds: [''], expiresAt: '2026-12-31T23:59:00Z', expiredUrl: 'https://example.com/expired', password: 'launch', cloaked: true, ios: 'https://example.com/ios', android: 'https://example.com/android', geo: { SA: 'https://example.com/sa' } } ]) }); const links = await response.json(); ``` **Response** ```json [ { "id": "", "url": "https://example.com", "shortUrl": "https://hoko.to/abc123", "qrCode": "https://hoko.to/qrcode?text=https%3A%2F%2Fhoko.to%2Fabc123%3Fqr%3D1&size=512&errorCorrection=H&foreground=000000&background=FFFFFF&margin=1&format=svg", "title": null, "description": null, "image": null, "utm": null, "expiresAt": "2026-12-31T23:59:00Z", "expiredUrl": "https://example.com/expired", "password": "launch", "cloaked": true, "ios": "https://example.com/ios", "android": "https://example.com/android", "geo": { "SA": "https://example.com/sa" }, "collectionId": "", "tagIds": [""], "externalId": null, "tenantId": null, "partnerId": null, "createdAt": "2024-01-01T00:00:00Z" } ] ``` ### 400 Invalid request body (missing required fields or invalid values). **Request** ```bash curl -X POST "https://api.hoko.to/links" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "url": "invalid-url" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { url: 'invalid-url' } ]) }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X POST "https://api.hoko.to/links" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'POST', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required linksWrite scope. **Request** ```bash curl -X POST "https://api.hoko.to/links" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'POST', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["linksWrite"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X POST "https://api.hoko.to/links" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'POST', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X POST "https://api.hoko.to/links" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "url": "https://example.com", "title": "Example Link", "description": "An example link", "collectionId": "", "tagIds": [""], "utm": { "source": "google", "medium": "cpc", "campaign": "summer" } } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { url: 'https://example.com', title: 'Example Link', description: 'An example link', collectionId: '', tagIds: [''], utm: { source: 'google', medium: 'cpc', campaign: 'summer' } } ]) }); const links = await response.json(); ``` **Response** ```json [ { "id": "", "url": "https://example.com", "shortUrl": "https://hoko.to/abc123", "qrCode": "https://hoko.to/qrcode?text=https%3A%2F%2Fhoko.to%2Fabc123%3Fqr%3D1&size=512&errorCorrection=H&foreground=000000&background=FFFFFF&margin=1&format=svg", "title": "Example Link", "description": "An example link", "image": null, "utm": null, "expiresAt": null, "expiredUrl": null, "password": null, "cloaked": false, "ios": null, "android": null, "geo": null, "collectionId": "", "tagIds": [""], "externalId": null, "tenantId": null, "partnerId": null, "createdAt": "2024-01-01T00:00:00Z" } ] ``` > **Warning: Important Constraints** > The collectionId must reference an existing collection in your workspace. Each tagIds value must reference an existing tag in your workspace. The externalId must be unique within your workspace if provided. Plan limits may restrict the number of links you can create per request and overall. --- ### (PUT) Update/Upsert links Update existing links or create new ones with upsert operations. Perfect for synchronization scenarios. Docs URL: https://docs.hoko.to/links/put Markdown: https://docs.hoko.to/links/put/README.md ## Endpoint PUT /links The PUT endpoint implements an upsert operation, allowing you to update existing links or create new ones in a single request. This is particularly useful for synchronization scenarios where you want to ensure links exist with specific properties. If an id is provided in the request body, the endpoint updates the existing link with that ID. If the ID does not exist, the request fails. To create new links, omit the id field. Returns the updated or created links in the same order as the input array, making it easy to correlate requests with responses in bulk operations. **Endpoint** ```text PUT /links ``` ## Authentication Requires an authorized credential with permission for `linksWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body The request body must be an array of link objects. Include the id field to update an existing link, or omit it to create a new one. You can upsert up to 10,000 links in a single request. However, the actual maximum may be lower based on your subscription plan limits and available resources. | Parameter | Type | Required | Location | Description | | ------------ | ------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string (ULID) | Yes | body | Required when updating. Omit to create a new link. If provided, it must exist in your workspace or the request fails. | | url | string (URL) | No | body | HTTPS destination URL. Required when creating a new link (no id). Optional when updating. | | collectionId | string (ULID) | No | body | Collection ID. Required when creating a new link (no id). Optional when updating. | | tagIds | string[] | No | body | Existing tag IDs to assign. When updating, replaces tag assignments if provided. Send `[]` to clear all tags. | | title | string | No | body | Link title. Only changes when provided. | | description | string | No | body | Link description. Only changes when provided. | | image | string (URL) | No | body | HTTPS preview image URL. Only changes when provided. | | utm | object | No | body | UTM parameters object. Insert entries accept string values; update entries may send null for individual keys to clear them. | | expiresAt | string/null | No | body | ISO date-time when the link should expire. Send null to clear. Requires link expiration when setting a value. | | expiredUrl | string/null | No | body | HTTPS destination used after expiration. Send null to clear. Requires link expiration when setting a value. | | password | string/null | No | body | Password required before resolving the destination. Send null to clear. Requires password protection when set. | | cloaked | boolean/null | No | body | Render the resolved destination in an iframe. Send false/null to clear. When true, the destination is preflighted and rejected with 400 if it currently blocks iframe rendering. | | ios | string/null | No | body | HTTPS destination for iOS visitors. Send null to clear. Requires device targeting when setting a value. | | android | string/null | No | body | HTTPS destination for Android visitors. Send null to clear. Requires device targeting when setting a value. | | geo | object/null | No | body | Uppercase country-code HTTPS destination map. Send null to clear on updates or omit/null on inserts for no geo targeting. Requires geo targeting when setting destinations. | | externalId | string | No | body | External ID for syncing. Must be unique in workspace when provided. | | tenantId | string | No | body | Tenant identifier. Optional. | | partnerId | string (ULID) | No | body | Partner ID for attribution. Optional. | > **Warning: Plan Limits** > The actual maximum number of links you can upsert per request may be lower than 10,000 based on your subscription plan limits and available resources. The system will enforce both the hard limit (10,000) and your plan-specific limits. ## Advanced Link Behavior Advanced fields are applied only when they are set on the link and your workspace plan supports the feature. When updating, include at least one mutable field besides id; omitted fields are left unchanged. Send `null` to clear nullable fields only on entries that include `id`, and send `false` or `null` to disable `cloaked`. Entries without `id` use the same create validation as `POST /links`: nullable clears are not accepted except `geo: null` for no geo targeting. For tags, omit `tagIds` to keep existing assignments or send `[]` to clear them. All URL fields accepted by this endpoint must use `https:`. This includes `url`, `image`, `expiredUrl`, `ios`, `android`, and every URL value in `geo`. - `password`: Visitors must enter the password before Hoko resolves the final destination. A correct password stores a secure, HTTP-only cookie scoped to that short link, so the same visitor can continue without re-entering it. - `expiresAt`: Use an ISO date-time with timezone offset, such as `2026-12-31T23:59:00Z`. When the current server time is later than `expiresAt`, the link is expired. If `expiredUrl` is set, Hoko sends visitors there. If it is not set, Hoko shows an expired-link page. - `ios` and `android`: Device destinations are selected from the visitor's User-Agent. iOS and Android checks run before geo targeting. - `geo`: Map ISO 3166-1 alpha-2 country codes to destination URLs, for example `{ "SA": "https://example.com/sa" }`. Use uppercase country codes. Country detection is best-effort and uses trusted edge country headers when available, then IP lookup. - `cloaked`: Hoko renders the resolved destination in a full-page iframe. Create and update requests preflight the active destination and return 400 if it currently blocks iframe rendering. Resolution order is: password gate, expiration, iOS/Android targeting, geo targeting, default `url`, then cloaking. Expired links do not run device or geo targeting. ## Status Codes ### 200 Links updated or created successfully. **Request** ```bash curl -X PUT "https://api.hoko.to/links" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "id": "", "url": "https://updated.com", "title": "Updated Link", "expiresAt": "2026-12-31T23:59:00Z", "expiredUrl": "https://updated.com/expired", "cloaked": true, "ios": "https://updated.com/ios", "android": "https://updated.com/android", "geo": { "US": "https://updated.com/us" }, "collectionId": "", "tagIds": [""] } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'PUT', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { id: '', url: 'https://updated.com', title: 'Updated Link', expiresAt: '2026-12-31T23:59:00Z', expiredUrl: 'https://updated.com/expired', cloaked: true, ios: 'https://updated.com/ios', android: 'https://updated.com/android', geo: { US: 'https://updated.com/us' }, collectionId: '', tagIds: [''] } ]) }); const links = await response.json(); ``` **Response** ```json [ { "id": "", "url": "https://updated.com", "shortUrl": "https://hoko.to/abc123", "qrCode": "https://hoko.to/qrcode?text=https%3A%2F%2Fhoko.to%2Fabc123%3Fqr%3D1&size=512&errorCorrection=H&foreground=000000&background=FFFFFF&margin=1&format=svg", "title": "Updated Link", "description": null, "image": null, "utm": null, "expiresAt": "2026-12-31T23:59:00Z", "expiredUrl": "https://updated.com/expired", "password": null, "cloaked": true, "ios": "https://updated.com/ios", "android": "https://updated.com/android", "geo": { "US": "https://updated.com/us" }, "collectionId": "", "tagIds": [""], "externalId": null, "tenantId": null, "partnerId": null, "createdAt": "2024-01-01T00:00:00Z" } ] ``` ### 400 Invalid request body (missing required fields or invalid values). **Request** ```bash curl -X PUT "https://api.hoko.to/links" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "url": "invalid-url" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'PUT', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { url: 'invalid-url' } ]) }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X PUT "https://api.hoko.to/links" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'PUT', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required linksWrite scope. **Request** ```bash curl -X PUT "https://api.hoko.to/links" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'PUT', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["linksWrite"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X PUT "https://api.hoko.to/links" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'PUT', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X PUT "https://api.hoko.to/links" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "id": "", "url": "https://updated.com", "title": "Updated Link", "collectionId": "", "tagIds": [""] } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'PUT', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { id: '', url: 'https://updated.com', title: 'Updated Link', collectionId: '', tagIds: [''] } ]) }); const links = await response.json(); ``` **Response** ```json [ { "id": "", "url": "https://updated.com", "shortUrl": "https://hoko.to/abc123", "qrCode": "https://hoko.to/qrcode?text=https%3A%2F%2Fhoko.to%2Fabc123%3Fqr%3D1&size=512&errorCorrection=H&foreground=000000&background=FFFFFF&margin=1&format=svg", "title": "Updated Link", "description": null, "image": null, "utm": null, "expiresAt": null, "expiredUrl": null, "password": null, "cloaked": false, "ios": null, "android": null, "geo": null, "collectionId": "", "tagIds": [""], "externalId": null, "tenantId": null, "partnerId": null, "createdAt": "2024-01-01T00:00:00Z" } ] ``` > **Info: Upsert Behavior** > When updating, include at least one mutable field besides id. Only the fields you include are changed and omitted fields keep their current values. To clear an optional field, send it explicitly as null on update entries. To replace tag assignments, send tagIds; to clear all tags, send tagIds as an empty array. When creating a new link (no id), url and collectionId are required and create validation matches POST. --- ### (DELETE) Delete links Delete one or more links using soft delete. Historical analytics data is preserved. Docs URL: https://docs.hoko.to/links/delete Markdown: https://docs.hoko.to/links/delete/README.md ## Endpoint DELETE /links Delete one or more links using soft delete. Soft delete marks links as deleted without permanently removing them from the database, allowing for potential recovery and maintaining referential integrity. Accepts an array of link IDs to delete. All specified links must belong to your workspace. The endpoint returns the IDs of successfully deleted links. Deleted links are no longer accessible via the API and will not appear in GET requests, but historical analytics data associated with these links is preserved. **Endpoint** ```text DELETE /links ``` ## Authentication Requires an authorized credential with permission for `linksWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body The request body must be an array of link IDs (ULIDs) to delete. You can delete up to 10,000 links in a single request. However, the actual maximum may be lower based on your subscription plan limits and available resources. | Parameter | Type | Required | Location | Description | | --------- | ------------- | -------- | -------- | ---------------------------------------------------------------------------------------- | | body | array | Yes | body | Array of link IDs (ULIDs) to delete. All IDs must be valid and belong to your workspace. | > **Warning: Request Size** > You can delete up to 10,000 links in a single request. Requests above 10,000 IDs are rejected. ## Status Codes ### 200 Links deleted successfully. **Request** ```bash curl -X DELETE "https://api.hoko.to/links" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ "" ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'DELETE', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify(['']) }); const result = await response.json(); ``` **Response** ```json { "deletedIds": [""] } ``` ### 400 Invalid request body (missing IDs, invalid ULIDs, or IDs not found in your workspace). **Request** ```bash curl -X DELETE "https://api.hoko.to/links" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ "invalid-id" ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'DELETE', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify(['invalid-id']) }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X DELETE "https://api.hoko.to/links" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'DELETE', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required linksWrite scope. **Request** ```bash curl -X DELETE "https://api.hoko.to/links" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'DELETE', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["linksWrite"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X DELETE "https://api.hoko.to/links" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'DELETE', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X DELETE "https://api.hoko.to/links" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ "" ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/links', { method: 'DELETE', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify(['']) }); const result = await response.json(); ``` **Response** ```json { "deletedIds": [""] } ``` > **Warning: Permanent Action** > Deleted links cannot be restored through the API. While the data is preserved for analytics purposes, the links themselves are no longer accessible. Ensure you have backups or exports before performing bulk deletions. --- ### Introduction Organize your links with collections. Collections are essential organizational units that help you structure and manage your link library. Docs URL: https://docs.hoko.to/collections/introduction Markdown: https://docs.hoko.to/collections/introduction/README.md ## Overview Collections, provide a powerful way to organize and categorize your links. Think of collections as containers that help you group related links together—whether by campaign, project, client, or any other organizational structure that makes sense for your workflow. Every link must belong to a collection, making collections a fundamental organizational unit in Hoko. Use collections to create logical groupings that make it easier to find, manage, and analyze your links. The Collections API provides full CRUD operations for managing your organizational structure. Create collections before creating links, and use them to maintain a clean, organized link library. - (GET) Retrieve collections with pagination and filtering - (POST) Create one or more collections to organize your links - (PUT) Update existing collections or create new ones with upsert - (DELETE) Soft delete collections while preserving link relationships > **Tip: Organization Strategy** > Create collections before creating links. Plan your collection structure to match your workflow—consider organizing by campaign, product line, marketing channel, or client. You can always reorganize later, but a good initial structure saves time. --- ### (GET) Get collections Retrieve collections from your workspace. Filter by collection ID or list all collections with pagination. Docs URL: https://docs.hoko.to/collections/get Markdown: https://docs.hoko.to/collections/get/README.md ## Endpoint GET /collections Retrieve collections from your workspace. Filter by collection ID to get specific collections, or omit the filter to retrieve all collections with pagination support. Use this endpoint to list your collections, verify collection existence before creating links, or build collection management interfaces. **Endpoint** ```text GET /collections ``` ## Authentication Requires an authorized credential with permission for `collectionsRead`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Query Parameters | Parameter | Type | Required | Location | Description | | --------- | ------------- | -------- | -------- | ------------------------------------------------------------------------------------------- | | id | string (ULID) | No | query | Filter by specific collection ID. Returns a single collection if found. | | take | number | No | query | Number of results to return (default: 50, min: 1, max: 5,000). | | skip | number | No | query | Number of results to skip for pagination (default: 0, min: 0). | | sort | string | No | query | Sort order by createdAt: "asc" for oldest first, "desc" for newest first (default: "desc"). | > **Warning: Request Limits** > The `take` parameter supports values from 1 to 5,000. Requests above 5,000 are rejected. ## Status Codes ### 200 Successfully retrieved collections. **Request** ```bash curl -X GET "https://api.hoko.to/collections?take=50&sort=desc" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections?take=50&sort=desc', { method: 'GET', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json [ { "id": "", "name": "Marketing Campaigns", "description": "All marketing links", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` ### 400 Invalid query parameters. This includes invalid ULID filters or invalid `take`, `skip`, or `sort` values. **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X GET "https://api.hoko.to/collections" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'GET', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required collectionsRead scope. **Request** ```bash curl -X GET "https://api.hoko.to/collections" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'GET', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["collectionsRead"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X GET "https://api.hoko.to/collections" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'GET', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X GET "https://api.hoko.to/collections?take=50&sort=desc" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections?take=50&sort=desc', { method: 'GET', headers: { Authorization: 'Bearer ' } }); const collections = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Marketing Campaigns", "description": "All marketing links", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` --- ### (POST) Create collections Create one or more collections to organize your links. Each collection requires a name. Docs URL: https://docs.hoko.to/collections/post Markdown: https://docs.hoko.to/collections/post/README.md ## Endpoint POST /collections Create one or more collections to organize your links. Collections are essential organizational units—every link must belong to a collection. Each collection requires a name for identification. Optionally include a description to provide additional context about the collection's purpose or contents. You can create multiple collections in a single request by providing an array of collection objects, making it easy to set up your organizational structure quickly. **Endpoint** ```text POST /collections ``` ## Authentication Requires an authorized credential with permission for `collectionsWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body The request body must be an array of collection objects. Each object represents one collection to create. You can create up to 10,000 collections in a single request. However, the actual maximum may be lower based on your subscription plan limits and available resources. | Parameter | Type | Required | Location | Description | | ----------- | ------ | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | Yes | body | The name of the collection. Used for identification and organization. Choose descriptive names that clearly indicate the collection's purpose. | | description | string | No | body | Optional description providing additional context about the collection. Useful for documentation and team collaboration. | > **Warning: Plan Limits** > The actual maximum number of collections you can create per request may be lower than 10,000 based on your subscription plan limits and available resources. The system will enforce both the hard limit (10,000) and your plan-specific limits. ## Status Codes ### 201 Collections created successfully. **Request** ```bash curl -X POST "https://api.hoko.to/collections" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "name": "Marketing Campaigns" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { name: 'Marketing Campaigns' } ]) }); ``` **Response** ```json [ { "id": "", "name": "Marketing Campaigns", "description": null, "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` ### 400 Invalid request body (missing required fields or invalid values). **Request** ```bash curl -X POST "https://api.hoko.to/collections" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ {} ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([{}]) }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X POST "https://api.hoko.to/collections" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'POST', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required collectionsWrite scope. **Request** ```bash curl -X POST "https://api.hoko.to/collections" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'POST', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["collectionsWrite"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X POST "https://api.hoko.to/collections" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'POST', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X POST "https://api.hoko.to/collections" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "name": "Marketing Campaigns", "description": "All marketing campaign links" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { name: 'Marketing Campaigns', description: 'All marketing campaign links' } ]) }); const collections = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Marketing Campaigns", "description": "All marketing campaign links", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` > **Info: Collection Requirements** > Every link must belong to a collection. Create collections before creating links, or ensure the collectionId you reference in link creation requests exists in your workspace. --- ### (PUT) Update/Upsert collections Update existing collections or create new ones with upsert operations. Docs URL: https://docs.hoko.to/collections/put Markdown: https://docs.hoko.to/collections/put/README.md ## Endpoint PUT /collections Upsert (update or insert) one or more collections. If id is provided, the collection is updated. If the ID does not exist, the request fails. To create new collections, omit the id field. This endpoint is useful for synchronization scenarios where you want to ensure collections exist with specific properties. **Endpoint** ```text PUT /collections ``` ## Authentication Requires an authorized credential with permission for `collectionsWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body The request body must be an array of collection objects. Include the id field to update an existing collection, or omit it to create a new one. You can upsert up to 10,000 collections in a single request. However, the actual maximum may be lower based on your subscription plan limits and available resources. | Parameter | Type | Required | Location | Description | | ----------- | ------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | id | string (ULID) | Yes | body | Required when updating. Omit to create a new collection. If provided, it must exist in your workspace or the request fails. | | name | string | No | body | The name of the collection. Required when creating a new collection (no id). Optional when updating. | | description | string/null | No | body | Optional description. PUT insert and update entries may send null for no description. Only changes when provided. | > **Info: Update Behavior** > When updating, include at least one mutable field besides id. Only the fields you include are changed. Omitted fields keep their current values. To clear a value, send it explicitly as null. PUT insert entries also accept `description: null`. > **Warning: Plan Limits** > The actual maximum number of collections you can upsert per request may be lower than 10,000 based on your subscription plan limits and available resources. The system will enforce both the hard limit (10,000) and your plan-specific limits. ## Status Codes ### 200 Collections updated or created successfully. **Request** ```bash curl -X PUT "https://api.hoko.to/collections" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "id": "", "name": "Updated Name" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'PUT', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { id: '', name: 'Updated Name' } ]) }); ``` **Response** ```json [ { "id": "", "name": "Updated Name", "description": null, "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` ### 400 Invalid request body (missing required fields or invalid values). **Request** ```bash curl -X PUT "https://api.hoko.to/collections" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ {} ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'PUT', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([{}]) }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X PUT "https://api.hoko.to/collections" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'PUT', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required collectionsWrite scope. **Request** ```bash curl -X PUT "https://api.hoko.to/collections" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'PUT', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["collectionsWrite"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X PUT "https://api.hoko.to/collections" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'PUT', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X PUT "https://api.hoko.to/collections" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "id": "", "name": "Updated Name", "description": "Updated description" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'PUT', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { id: '', name: 'Updated Name', description: 'Updated description' } ]) }); const collections = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Updated Name", "description": "Updated description", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` --- ### (DELETE) Delete collections Delete one or more collections using soft delete. Docs URL: https://docs.hoko.to/collections/delete Markdown: https://docs.hoko.to/collections/delete/README.md ## Endpoint DELETE /collections Delete one or more collections using soft delete. Soft delete marks collections as deleted without permanently removing them from the database. Accepts an array of collection IDs to delete. All specified collections must belong to your workspace. **Endpoint** ```text DELETE /collections ``` ## Authentication Requires an authorized credential with permission for `collectionsWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body The request body must be an array of collection IDs (ULIDs) to delete. You can delete up to 10,000 collections in a single request. Requests above 10,000 IDs are rejected. | Parameter | Type | Required | Location | Description | | --------- | ------------- | -------- | -------- | ---------------------------------------------------------------------------------------------- | | body | array | Yes | body | Array of collection IDs (ULIDs) to delete. All IDs must be valid and belong to your workspace. | > **Warning: Request Size** > Ensure the request body contains at least one valid collection ID. ## Status Codes ### 200 Collections deleted successfully. **Request** ```bash curl -X DELETE "https://api.hoko.to/collections" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ "" ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'DELETE', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify(['']) }); ``` **Response** ```json { "deletedIds": [""] } ``` ### 400 Invalid request body (missing IDs, invalid ULIDs, or IDs not found in your workspace). **Request** ```bash curl -X DELETE "https://api.hoko.to/collections" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ "invalid-id" ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'DELETE', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify(['invalid-id']) }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X DELETE "https://api.hoko.to/collections" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'DELETE', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required collectionsWrite scope. **Request** ```bash curl -X DELETE "https://api.hoko.to/collections" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'DELETE', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["collectionsWrite"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X DELETE "https://api.hoko.to/collections" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'DELETE', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X DELETE "https://api.hoko.to/collections" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ "" ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/collections', { method: 'DELETE', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify(['']) }); const result = await response.json(); ``` **Response** ```json { "deletedIds": [""] } ``` > **Warning: Important Note** > Deleted collections cannot be restored through the API. Links that belong to deleted collections will still exist but may need to be moved to active collections for proper organization. --- ### Custom API clients Connect any HTTPS client to Hoko's unversioned REST API. Docs URL: https://docs.hoko.to/custom-api Markdown: https://docs.hoko.to/custom-api/README.md ## Connect a custom client Use any HTTPS client that can send JSON and request headers. The canonical API base is `https://api.hoko.to`. The API has no version prefix. Resource routes are the public HTTP contract and use the same shared engine as the dashboard, CLI, and MCP adapters. Create an API key in Hoko with only the scopes your job needs. Custom clients use manual API-key setup. Hoko does not provide a native SDK or OAuth connection for this path. ## Authenticate Send the key in `X-API-Key`: ```sh curl --request GET 'https://api.hoko.to/links' \ --header 'X-API-Key: ' \ --header 'Accept: application/json' ``` `Authorization: Bearer ` is also accepted. Do not send both headers. Treat the key as a secret, keep it outside source control, and rotate it when a job or person no longer needs access. ## Read and write links The feature route keeps the established response shapes: ```sh curl --request POST 'https://api.hoko.to/links' \ --header 'X-API-Key: ' \ --header 'Content-Type: application/json' \ --header 'X-Request-Id: custom-client-create-001' \ --data '[{"url":"https://example.com/campaign","collectionId":""}]' ``` The request body is an array for this existing bulkable route. The response is an array of created link records. `DELETE /links` also accepts an array of link IDs. Use the resource route for each HTTP request. Engine operation names remain metadata used by the CLI and MCP adapters; they are not public HTTP paths. ## Request IDs and responses Send a unique `X-Request-Id` for each request. Hoko carries it through the shared engine and logging path so support can correlate a request. Keep the value free of secrets or personal data. Successful responses use the route's existing JSON shape and a 2xx status. Errors include an `error` message and stable `code` where the route exposes one. A client must not treat a 2xx response as permission to retry a mutation unless the operation documents that behavior. ## Scopes and errors API-key scopes are checked at the resource boundary: | Response | Meaning | Client action | | -------- | ---------------------------------------------------- | ------------------------------------------------------------------- | | `400` | Malformed JSON or invalid operation input | Fix the request. Do not retry unchanged. | | `401` | Missing, invalid, or revoked credential | Replace or revoke the credential in the client. | | `403` | The key lacks the required scope or workspace access | Grant the narrow required scope or choose an allowed resource. | | `404` | Missing resource | Check the resource path or resource ID. | | `429` | The shared admission limit is exhausted | Wait for `Retry-After`, then retry a safe request. | | `5xx` | Hoko could not complete the request | Retry only a documented safe operation and preserve the request ID. | Invalid credentials do not reveal workspace data or rate counters. A revoked key fails on the next protected request. A key cannot regain access by changing the workspace header. ## Rate limits and retries Every root REST operation consumes one shared workspace admission. Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. A `429` response includes `Retry-After` in seconds. Retry reads after the advertised delay. Treat link creation, updates, and deletes as non-idempotent unless the operation's contract explicitly adds durable idempotency. If a write times out after reaching Hoko, inspect the result before sending another write. ## Security checklist - Store `HOKO_API_KEY` in a secret manager or process environment. - Give the key the smallest required scopes. - Keep request and response logs free of API keys, cookies, and destinations. - Rotate or revoke the key when its owner or job changes. - Test against a disposable workspace before enabling a production job. --- ### Introduction Create, read, update, and delete tags for categorizing and organizing your links. Docs URL: https://docs.hoko.to/tags/introduction Markdown: https://docs.hoko.to/tags/introduction/README.md ## Overview Tags help categorize and filter your links, providing a flexible labeling system that complements collections. While collections organize links into folders, tags allow you to apply multiple labels to a single link, enabling cross-cutting categorization. Use tags to mark links by campaign type, content category, target audience, priority level, or any other dimension that helps you organize and find your links. A single link can have multiple tags, making it easy to filter and search across different organizational axes. The Tags API provides full CRUD operations for managing your tag library. Create tags with custom names and colors, update them as your needs evolve, and delete tags that are no longer needed. - (GET) Retrieve tags with pagination and filtering - (POST) Create one or more tags with custom names and colors - (PUT) Update existing tags or create new ones with upsert - (DELETE) Permanently delete tags (hard delete) > **Tip: Tag Strategy** > Plan your tag structure to complement your collection organization. Use tags for cross-cutting concerns that span multiple collections, such as campaign types, content categories, or priority levels. Choose descriptive tag names and use colors to visually distinguish different tag categories. --- ### (GET) Get tags Retrieve tags from your workspace. Filter by tag ID or list all tags with pagination. Docs URL: https://docs.hoko.to/tags/get Markdown: https://docs.hoko.to/tags/get/README.md ## Endpoint GET /tags Retrieve tags by id. Supports pagination with take, skip, and sorting by tag id. Use this endpoint to list your tags, verify tag existence, or build tag management interfaces. **Endpoint** ```text GET /tags ``` ## Authentication Requires an authorized credential with permission for `tagsRead`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Query Parameters | Parameter | Type | Required | Location | Description | | --------- | ------------- | -------- | -------- | ---------------------------------------------------------------------------------------- | | id | string (ULID) | No | query | Filter by specific tag ID. Returns a single tag if found. | | take | number | No | query | Number of results to return (default: 50, min: 1, max: 5,000). | | skip | number | No | query | Number of results to skip for pagination (default: 0, min: 0). | | sort | string | No | query | Sort order by tag id: "asc" for oldest first, "desc" for newest first (default: "desc"). | > **Warning: Request Limits** > The `take` parameter supports values from 1 to 5,000. Requests above 5,000 are rejected. ## Status Codes ### 200 Successfully retrieved tags. **Request** ```bash curl -X GET "https://api.hoko.to/tags?take=50&sort=desc" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags?take=50&sort=desc', { method: 'GET', headers: { Authorization: 'Bearer ' } }); const tags = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Marketing", "color": "blue" } ] ``` ### 400 Invalid query parameters. This includes invalid ULID filters or invalid `take`, `skip`, or `sort` values. **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X GET "https://api.hoko.to/tags" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'GET', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required tagsRead scope. **Request** ```bash curl -X GET "https://api.hoko.to/tags" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'GET', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["tagsRead"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X GET "https://api.hoko.to/tags" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'GET', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X GET "https://api.hoko.to/tags?take=50&sort=desc" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags?take=50&sort=desc', { method: 'GET', headers: { Authorization: 'Bearer ' } }); const tags = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Marketing", "color": "blue" } ] ``` --- ### (POST) Create tags Create one or more tags. Each tag requires a name, and color is optional. Docs URL: https://docs.hoko.to/tags/post Markdown: https://docs.hoko.to/tags/post/README.md ## Endpoint POST /tags Create one or more tags. Accepts an array of tag objects. Each tag requires a name. Color is optional (defaults to "slate"). **Endpoint** ```text POST /tags ``` ## Authentication Requires an authorized credential with permission for `tagsWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body The request body must be an array of tag objects. Each object represents one tag to create. You can create up to 10,000 tags in a single request. However, the actual maximum may be lower based on your subscription plan limits and available resources. | Parameter | Type | Required | Location | Description | | --------- | ------ | -------- | -------- | -------------------------------------------------------------------------------------- | | name | string | Yes | body | The name of the tag. Choose descriptive names that clearly indicate the tag's purpose. | | color | string | No | body | The color of the tag. Must be one of the available color values (default: "slate"). | > **Warning: Plan Limits** > The actual maximum number of tags you can create per request may be lower than 10,000 based on your subscription plan limits and available resources. The system will enforce both the hard limit (10,000) and your plan-specific limits. ## Status Codes ### 201 Tags created successfully. **Request** ```bash curl -X POST "https://api.hoko.to/tags" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "name": "Marketing", "color": "blue" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { name: 'Marketing', color: 'blue' } ]) }); const tags = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Marketing", "color": "blue" } ] ``` ### 400 Invalid request body (missing required fields or invalid values). **Request** ```bash curl -X POST "https://api.hoko.to/tags" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "name": "Marketing", "color": "invalid-color" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { name: 'Marketing', color: 'invalid-color' } ]) }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X POST "https://api.hoko.to/tags" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'POST', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required tagsWrite scope. **Request** ```bash curl -X POST "https://api.hoko.to/tags" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'POST', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["tagsWrite"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X POST "https://api.hoko.to/tags" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'POST', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples ### Available Colors Type: color - slate - gray - zinc - neutral - stone - red - orange - amber - yellow - lime - green - emerald - teal - cyan - sky - blue - indigo - violet - purple - fuchsia - pink - rose **Request** ```bash curl -X POST "https://api.hoko.to/tags" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "name": "Marketing", "color": "blue" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { name: 'Marketing', color: 'blue' } ]) }); const tags = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Marketing", "color": "blue" } ] ``` --- ### (PUT) Update/Upsert tags Update existing tags or create new ones with upsert operations. Docs URL: https://docs.hoko.to/tags/put Markdown: https://docs.hoko.to/tags/put/README.md ## Endpoint PUT /tags Upsert (update or insert) one or more tags. If id is provided, the tag is updated. If the ID does not exist, the request fails. To create new tags, omit the id field. This endpoint is useful for synchronization scenarios where you want to ensure tags exist with specific properties. **Endpoint** ```text PUT /tags ``` ## Authentication Requires an authorized credential with permission for `tagsWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body The request body must be an array of tag objects. Include the id field to update an existing tag, or omit it to create a new one. You can upsert up to 10,000 tags in a single request. However, the actual maximum may be lower based on your subscription plan limits and available resources. | Parameter | Type | Required | Location | Description | | --------- | ------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | id | string (ULID) | Yes | body | Required when updating. Omit to create a new tag. If provided, it must exist in your workspace or the request fails. | | name | string | No | body | The name of the tag. Required when creating a new tag (no id). Optional when updating. | | color | string | No | body | The color of the tag. Optional. Defaults to \"slate\" when creating a new tag. | > **Info: Update Behavior** > When updating, include at least one mutable field besides id. Only the fields you include are changed. Omitted fields keep their current values. For new tags (no id), color defaults to \"slate\" if omitted. > **Warning: Plan Limits** > The actual maximum number of tags you can upsert per request may be lower than 10,000 based on your subscription plan limits and available resources. The system will enforce both the hard limit (10,000) and your plan-specific limits. ## Status Codes ### 200 Tags updated or created successfully. **Request** ```bash curl -X PUT "https://api.hoko.to/tags" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "id": "", "name": "Updated Tag", "color": "green" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'PUT', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { id: '', name: 'Updated Tag', color: 'green' } ]) }); const tags = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Updated Tag", "color": "green" } ] ``` ### 400 Invalid request body (missing required fields or invalid values). **Request** ```bash curl -X PUT "https://api.hoko.to/tags" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "name": "Tag", "color": "invalid-color" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'PUT', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { name: 'Tag', color: 'invalid-color' } ]) }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X PUT "https://api.hoko.to/tags" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'PUT', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required tagsWrite scope. **Request** ```bash curl -X PUT "https://api.hoko.to/tags" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'PUT', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["tagsWrite"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X PUT "https://api.hoko.to/tags" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'PUT', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples ### Available Colors Type: color - slate - gray - zinc - neutral - stone - red - orange - amber - yellow - lime - green - emerald - teal - cyan - sky - blue - indigo - violet - purple - fuchsia - pink - rose **Request** ```bash curl -X PUT "https://api.hoko.to/tags" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "id": "", "name": "Updated Tag", "color": "green" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'PUT', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { id: '', name: 'Updated Tag', color: 'green' } ]) }); const tags = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Updated Tag", "color": "green" } ] ``` --- ### (DELETE) Delete tags Permanently delete one or more tags (hard delete). Docs URL: https://docs.hoko.to/tags/delete Markdown: https://docs.hoko.to/tags/delete/README.md ## Endpoint DELETE /tags Delete one or more tags (hard delete). This permanently removes tags from your workspace. Accepts an array of tag IDs to delete. All specified tags must belong to your workspace. **Endpoint** ```text DELETE /tags ``` ## Authentication Requires an authorized credential with permission for `tagsWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body The request body must be an array of tag IDs (ULIDs) to delete. You can delete up to 10,000 tags in a single request. Requests above 10,000 IDs are rejected. | Parameter | Type | Required | Location | Description | | --------- | ------------- | -------- | -------- | --------------------------------------------------------------------------------------- | | body | array | Yes | body | Array of tag IDs (ULIDs) to delete. All IDs must be valid and belong to your workspace. | > **Warning: Request Size** > Ensure the request body contains at least one valid tag ID. ## Status Codes ### 200 Tags deleted successfully. **Request** ```bash curl -X DELETE "https://api.hoko.to/tags" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ "" ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'DELETE', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify(['']) }); const result = await response.json(); ``` **Response** ```json { "deletedIds": [""] } ``` ### 400 Invalid request body (missing IDs, invalid ULIDs, or IDs not found in your workspace). **Request** ```bash curl -X DELETE "https://api.hoko.to/tags" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ "invalid-id" ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'DELETE', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify(['invalid-id']) }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X DELETE "https://api.hoko.to/tags" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'DELETE', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required tagsWrite scope. **Request** ```bash curl -X DELETE "https://api.hoko.to/tags" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'DELETE', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["tagsWrite"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X DELETE "https://api.hoko.to/tags" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'DELETE', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X DELETE "https://api.hoko.to/tags" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ "" ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/tags', { method: 'DELETE', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify(['']) }); const result = await response.json(); ``` **Response** ```json { "deletedIds": [""] } ``` > **Warning: Permanent Action** > Deleted tags cannot be restored. This is a hard delete operation that permanently removes tags from your workspace. Links that had these tags will no longer have those tag associations. --- ### Introduction Retrieve click analytics and performance data for your links. Gain insights into traffic patterns, user behavior, and campaign effectiveness. Docs URL: https://docs.hoko.to/analytics/introduction Markdown: https://docs.hoko.to/analytics/introduction/README.md ## Overview The Analytics API provides read-only access to comprehensive click data and analytics for your links. Track every click, understand your audience, and measure campaign performance with detailed insights. Every click on your short links is automatically tracked and enriched with metadata including device information, geographic location, browser details, referrer data, and UTM parameters. This data is immediately available through the Analytics API for real-time analysis and reporting. Use the Analytics API to build custom dashboards, generate reports, analyze traffic patterns, measure campaign ROI, and understand how users interact with your links across different channels and devices. - (GET) Retrieve click analytics with flexible filtering by link, partner, or date range - Detailed click data including device, location, browser, and UTM parameters - Support for pagination and sorting to efficiently process large datasets - Real-time analytics data available immediately after clicks occur > **Info: Data Availability** > Analytics data is available immediately after a click occurs. Use date range filters to analyze specific time periods, and combine with link or partner filters to drill down into specific segments of your traffic. --- ### (GET) Get analytics Retrieve click analytics and performance data for your links. Filter by link, partner, or date range. Docs URL: https://docs.hoko.to/analytics/get Markdown: https://docs.hoko.to/analytics/get/README.md ## Endpoint GET /analytics Retrieve click analytics and performance data for your links. Filter by link, partner, or date range to analyze specific segments of your traffic. Supports flexible filtering and pagination, making it easy to extract insights from large datasets. Results include detailed click information including device, location, browser, and UTM parameters. **Endpoint** ```text GET /analytics ``` ## Authentication Requires an authorized credential with permission for `analyticsRead`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Query Parameters | Parameter | Type | Required | Location | Description | | --------- | --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | linkId | string (ULID) | No | query | Filter analytics by specific link ID. Returns click data only for the specified link. | | partnerId | string (ULID) | No | query | Filter analytics by partner ID. Returns click data for all links associated with the specified partner. | | startDate | string (UTC ISO 8601) | No | query | Start date for the date range filter. Must be a UTC timestamp with trailing `Z` (e.g., "2024-01-01T00:00:00Z"). Offsets such as `+03:00` are rejected. | | endDate | string (UTC ISO 8601) | No | query | End date for the date range filter. Must be a UTC timestamp with trailing `Z` (e.g., "2024-01-31T23:59:59Z"). Offsets such as `+03:00` are rejected. | | take | number | No | query | Number of results to return (default: 50, min: 1, max: 5,000). Use pagination to retrieve large datasets efficiently. | | skip | number | No | query | Number of results to skip for pagination (default: 0, min: 0). Use with take to implement pagination. | | sort | string | No | query | Sort order by createdAt: "asc" for oldest clicks first, "desc" for newest clicks first (default: "desc"). | > **Warning: Request Limits** > The `take` parameter supports values from 1 to 5,000. Requests above 5,000 are rejected. > **Info: Retention Window** > Results are clamped to your workspace plan retention window and to the current server time. If `startDate` is earlier than the retention window, the effective start is moved forward. If `endDate` is in the future, the effective end is the current server time. ## Status Codes ### 200 Successfully retrieved analytics data. **Request** ```bash curl -X GET "https://api.hoko.to/analytics?linkId=&take=50" \ -H "Authorization: Bearer " ``` **Request** ```javascript const params = new URLSearchParams({ linkId: '', take: '50' }); const response = await fetch(`https://api.hoko.to/analytics?${params}`, { method: 'GET', headers: { Authorization: 'Bearer ' } }); const analytics = await response.json(); ``` **Response** ```json [ { "id": "", "linkId": "", "partnerId": null, "visitorId": null, "visitorSessionId": null, "referrer": null, "destination": null, "shortId": null, "utm": null, "externalId": null, "tenantId": null, "expired": false, "secured": false, "scanned": false, "geoTargeted": false, "iosTargeted": false, "androidTargeted": false, "origin": null, "pathname": null, "search": null, "browserLanguageCode": null, "browserLanguageRegion": null, "browserName": "Chrome", "browserVersion": null, "osName": null, "osVersion": null, "deviceVendor": null, "deviceModel": null, "deviceType": "desktop", "ipAddress": null, "continent": null, "country": "United States", "countryCode": null, "region": null, "city": null, "district": null, "zip": null, "latitude": null, "longitude": null, "mobile": false, "proxy": false, "hosting": false, "createdAt": "2024-01-01T00:00:00Z" } ] ``` ### 400 Invalid query parameters (e.g., malformed dates or ULIDs). **Request** ```bash curl -X GET "https://api.hoko.to/analytics?startDate=invalid-date" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/analytics?startDate=invalid-date', { method: 'GET', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X GET "https://api.hoko.to/analytics" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/analytics', { method: 'GET', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required analyticsRead scope. **Request** ```bash curl -X GET "https://api.hoko.to/analytics" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/analytics', { method: 'GET', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["analyticsRead"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X GET "https://api.hoko.to/analytics" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/analytics', { method: 'GET', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X GET "https://api.hoko.to/analytics?linkId=&startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z&take=50" \ -H "Authorization: Bearer " ``` **Request** ```javascript const params = new URLSearchParams({ linkId: '', startDate: '2024-01-01T00:00:00Z', endDate: '2024-01-31T23:59:59Z', take: '50' }); const response = await fetch(`https://api.hoko.to/analytics?${params}`, { method: 'GET', headers: { Authorization: 'Bearer ' } }); const analytics = await response.json(); ``` **Response** ```json [ { "id": "", "linkId": "", "partnerId": "", "visitorId": "", "visitorSessionId": "session_123", "referrer": "https://google.com", "destination": "https://example.com", "shortId": "abc123", "utm": { "source": "google", "medium": "cpc", "campaign": "summer" }, "externalId": "ext_123", "tenantId": "tenant_123", "expired": false, "secured": false, "scanned": false, "geoTargeted": false, "iosTargeted": false, "androidTargeted": false, "origin": null, "pathname": null, "search": null, "browserLanguageCode": null, "browserLanguageRegion": null, "browserName": "Chrome", "browserVersion": "120.0", "osName": "Windows", "osVersion": "10", "deviceVendor": null, "deviceModel": null, "deviceType": "desktop", "ipAddress": null, "continent": null, "country": "United States", "countryCode": "US", "region": null, "city": "New York", "district": null, "zip": null, "latitude": null, "longitude": null, "mobile": false, "proxy": false, "hosting": false, "createdAt": "2024-01-01T00:00:00Z" } ] ``` --- ### Connected apps Read the Apps catalog, connection states, and access rules for Hoko integrations. Docs URL: https://docs.hoko.to/integrations/apps Markdown: https://docs.hoko.to/integrations/apps/README.md ## Shared engine ChatGPT has a documented private OAuth setup for bounded native use. Public marketplace publication and host registration remain separate distribution gates. The dashboard, REST API, CLI, and MCP invoke the same named engine operations. Each interface provides authentication evidence. The engine applies authentication, authorization, usage, and rate-limit policy before it calls storage or database ports. Apps is a dashboard feature under Integrations. It does not create another API, another OAuth issuer, or another credential store. ## Connection direction ChatGPT is an inbound host. ChatGPT receives an Hoko OAuth grant and calls Hoko tools through MCP. Hoko does not call ChatGPT and does not receive a ChatGPT API key. An OpenAPI document describes the Hoko API contract. It does not connect an external provider account. Hoko does not list Slack, Notion, or another outbound provider as connected until that provider has a reviewed adapter, an authorization flow, and credential storage. ## Host setup cards The catalog contains setup guidance for these hosts: | Host | Setup mode | Authentication | | ----------------------------- | ----------------------------------------------------------------------------------------------- | -------------- | | ChatGPT | Manual private OAuth setup for bounded native use; public listing remains separate | OAuth | | Claude web and Claude Desktop | Manual private OAuth setup for bounded native use; public listing remains separate | OAuth | | Claude Code | Manual remote MCP setup | API key | | Cursor | Manual `mcp.json` setup | API key | | VS Code | Manual `mcp.json` setup | API key | | GitHub Copilot | Manual remote MCP setup | API key | | Gemini CLI | Manual settings.json or `gemini mcp add` setup for Standard, Enterprise, or paid API-key access | API key | | Windsurf | Manual setup. Hoko has not verified a host round trip | API key | | Zapier and n8n | Manual remote MCP setup | API key | | Make | Private custom app preview or manual REST setup. Make is not listed as a native MCP client | API key | | Custom MCP clients | Manual Streamable HTTP setup | API key | | Custom API clients | Manual REST setup | API key | These cards describe documented setup paths. They do not claim a native listing, one-click install, or Hoko verification. Use `https://mcp.hoko.to` as the canonical MCP endpoint. A manual MCP client that supports bearer headers can use this configuration after you create an API key in **Dashboard → Integrations → API Keys**: ```json { "mcpServers": { "hoko": { "url": "https://mcp.hoko.to", "headers": { "Authorization": "Bearer " } } } } ``` Keep the key in the host secret store. Use the host guide for the bounded private setup. Native account approval, public listing, and one-click distribution remain separate provider gates. Zapier, n8n, Make, and similar tools can call MCP or the REST API. Slack, Notion, and Linear can be automated through those tools and Hoko API calls; Hoko has no native outbound connectors for them. API-key and bearer access covers the operations allowed by that key's scopes. It does not provide human-only profile, personal Apps, API-key management, upload, or billing access. Use the Dashboard for those features. ## Outbound provider directory The catalog contains 47 entries: 13 clients and 34 business systems. The [Help app guides](https://help.hoko.to/apps) explain user setup. This reference records provider fields, supported contracts, and deployment requirements. Availability distinguishes manual recipes from configured provider connections and public distribution. A documented recipe does not imply a native account connection or marketplace listing. Provider approval and app registration remain separate requirements. A Hoko API key authenticates calls to Hoko. Provider credentials authenticate calls to the provider and remain in the customer-owned recipe or encrypted provider connection. They are not Hoko API keys. Use only the documented provider permissions; native OAuth, public registration, and incoming provider webhooks have their own requirements. Use the [automation recipes guide](https://docs.hoko.to/integrations/automation), the [link.created receiver guide](https://docs.hoko.to/integrations/link-created), and the [Google Tag Manager template guide](https://docs.hoko.to/integrations/google-tag-manager) for the first customer-owned implementation paths. Download the private [Power Automate connector](https://docs.hoko.to/integrations/power-platform). Pipedream Workflows is archived because the provider is retiring Workflows and String. Hoko has not implemented a Pipedream Connect adapter. The [private Zapier actions](https://docs.hoko.to/integrations/zapier) add create-link and exact external-ID lookup setup. The local preview has no verified Zapier import or public listing. Every guide also has a `README.md` route for agents, listed in [llms.txt](https://docs.hoko.to/llms.txt). The [private n8n node](https://docs.hoko.to/integrations/n8n) adds `Create Link` and exact external-ID lookup actions. The package targets n8n `2.42.x` with Node.js 24. This is a private, self-hosted package; n8n Cloud and community publication are not included. | App | Required fields | Minimum useful path | Readiness and limit | Provider documentation | | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Shopify](https://help.hoko.to/apps/shopify) | Shop domain, app install, offline token, scopes, product and variant IDs, webhook IDs | Connect a development store and create a product link | Connection. Protected customer data, app distribution, and checkout click identity remain gated | [Authentication](https://shopify.dev/docs/apps/build/authentication-authorization), [webhooks](https://shopify.dev/docs/apps/build/webhooks) | | [Salla](https://help.hoko.to/apps/salla) | Merchant and store IDs, app state, access and refresh token, scopes, product and order IDs | Connect a demo store and create a product link | Provider access. Partner app, Easy Mode, event security, and App Store review required | [Authorization](https://docs.salla.dev/421118m0), [webhooks](https://docs.salla.dev/421119m0) | | [Zid](https://help.hoko.to/apps/zid) | Store and merchant IDs, OAuth state, manager token, scopes, product and order IDs | Connect a development store and create a product link | Provider access. Partner approval, callback registration, activation, and event authentication required | [Authorization](https://docs.zid.sa/authorization), [webhooks](https://docs.zid.sa/webhooks) | | [WooCommerce](https://help.hoko.to/apps/woocommerce) | HTTPS store URL, consumer key and secret, product and order IDs, webhook IDs | Connect one merchant store and create a product link | Connection. Hosting, TLS, webhook secrets, and plugin distribution vary by store | [REST authentication](https://developer.woocommerce.com/docs/apis/rest-api/authentication), [webhooks](https://developer.woocommerce.com/docs/apis/rest-api/v3/webhooks/) | | [BigCommerce](https://help.hoko.to/apps/bigcommerce) | Store hash, OAuth state and token, scopes, product and order IDs, webhook IDs | Connect one OAuth store and create a product link | Connection. Callback verification and webhook authenticity need separate adapters | [Callbacks](https://docs.bigcommerce.com/developer/docs/integrations/apps/guide/handling-callbacks), [webhooks](https://docs.bigcommerce.com/developer/docs/integrations/webhooks/overview) | | [Adobe Commerce](https://help.hoko.to/apps/adobe-commerce) | Magento Open Source 2.4.8 store, merchant identity, OAuth 1.0a integration, product IDs | Install the Magento Open Source 2.4.8 product module and create one product link | Connection. The first adapter targets Magento Open Source only. Adobe Commerce SaaS is outside this path | [Authentication](https://developer.adobe.com/commerce/webapi/get-started/authentication/gs-authentication-oauth), [webhooks](https://developer.adobe.com/commerce/extensibility/app-management/installation/webhooks) | | [Buffer](https://help.hoko.to/apps/buffer) | Organization, channel profile, OAuth client, token, draft or post ID | Create a draft through the reviewed API path | Provider access. Current GraphQL access is preview and account eligibility applies | [API](https://developers.buffer.com/) | | [Sprout Social](https://help.hoko.to/apps/sprout-social) | Organization, profile, token or OAuth grant, draft ID | Create a draft for an eligible account | Provider access. Plan and API access must be confirmed; publishing is not assumed | [API](https://developers.sproutsocial.com/) | | [Publer](https://help.hoko.to/apps/publer) | Workspace, social account, token, draft or post ID | Create a reviewable draft | Provider access. Business entitlement and asynchronous job handling required | [API](https://publer.com/api) | | [Metricool](https://help.hoko.to/apps/metricool) | Account, brand ID, social profile, token, post ID | Create a reviewable post recipe | Provider access. Advanced or Custom plan and brand IDs required | [API](https://metricool.com/api/) | | [SocialPilot](https://help.hoko.to/apps/socialpilot) | Workspace, social profile, MCP connection, post ID | Compose Hoko MCP with the customer's SocialPilot MCP server | Recipe. This is a two-service composition, not a native Hoko connector | [MCP](https://www.socialpilot.co/integrations/mcp) | | [Typefully](https://help.hoko.to/apps/typefully) | Profile, OAuth or API credential, draft ID, publish state | Create a draft for review | Recipe. Publishing and reconciliation need provider proof | [API](https://typefully.com/developers) | | [Later](https://help.hoko.to/apps/later) | Workspace, social set, reporting token, report IDs | Resolve reporting contract before implementation | Contract review. Later Influence reporting and Later social publishing are separate products | [Developers](https://developers.later.com/) | | [Hootsuite](https://help.hoko.to/apps/hootsuite) | Organization, social account, OAuth state, token, post ID | Resolve current API and account access | Contract review. Current API and distribution contract remains unverified | [Developer portal](https://developer.hootsuite.com/) | | [Power Automate](https://help.hoko.to/apps/power-automate) | Environment, connector definition, API-key connection, flow ID | Import an actions-only OpenAPI projection | Recipe. Connector import needs OpenAPI 2.0 and has provider limits | [Custom connectors](https://learn.microsoft.com/en-us/connectors/custom-connectors), [OpenAPI import](https://learn.microsoft.com/en-us/connectors/custom-connectors/define-openapi-definition) | | [HubSpot](https://help.hoko.to/apps/hubspot) | Portal ID, private app token, scopes, contact and campaign IDs | Send a bounded campaign recipe | Recipe. Public app and webhook scope requirements remain gated | [Public apps](https://developers.hubspot.com/docs/guides/apps/public-apps/overview), [webhook scopes](https://developers.hubspot.com/changelog/announcement-scopes-will-be-required-for-apps-using-webhooks-or-crm-extensions) | | [Salesforce](https://help.hoko.to/apps/salesforce) | Org ID, External Client App, OAuth grant, scopes, campaign IDs | Send a bounded campaign recipe | Recipe. Public External Client App policy and inbound webhook work remain gated | [OAuth](https://developer.salesforce.com/docs/platform/api-rest/guide/intro-oauth-and-connected-apps.html) | | [Klaviyo](https://help.hoko.to/apps/klaviyo) | Account, provider API key, list and campaign IDs | Send a bounded campaign recipe | Recipe. Public OAuth allowlisting and inbound webhook contract remain gated | [Webhooks](https://developers.klaviyo.com/en/reference/webhooks_api_overview) | | [Mailchimp](https://help.hoko.to/apps/mailchimp) | Account, audience ID, provider API key, campaign ID | Send a bounded campaign recipe | Recipe. OAuth app registration and inbound event work remain gated | [Marketing API](https://mailchimp.com/developer/marketing/docs/), [OAuth apps](https://mailchimp.com/developer/marketing/build/start-developing/set-up-an-oauth-app) | | [Customer.io](https://help.hoko.to/apps/customerio) | Workspace, provider site or app key, campaign or journey ID, event ID | Send a measured event recipe | Recipe. Native connection and inbound webhook contract remain gated | [APIs](https://docs.customer.io/integrations/api/customerio-apis/), [webhooks](https://docs.customer.io/integrations/api/webhooks/) | | [Brevo](https://help.hoko.to/apps/brevo) | Account, provider API key, list and campaign IDs | Send a bounded campaign recipe | Recipe. Public OAuth distribution, recipient data, and inbound webhook work remain gated | [OAuth](https://developers.brevo.com/docs/oauth), [marketing webhooks](https://developers.brevo.com/docs/marketing-webhooks) | | [WordPress](https://help.hoko.to/apps/wordpress) | Site URL, application password or plugin token, post and link IDs | Add a link to one post through a reviewed plugin path | Recipe. Plugin install, capability checks, and post reconciliation required | [REST API](https://developer.wordpress.org/rest-api/), [authentication](https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/) | | [Webflow](https://help.hoko.to/apps/webflow) | Site ID, site token or OAuth grant, collection and item IDs, webhook secret | Create or update one CMS item with a Hoko link | Recipe. Only API-created webhooks provide the required signed delivery contract | [API](https://developers.webflow.com/data/reference), [webhooks](https://developers.webflow.com/data/reference/webhooks) | | [Ghost](https://help.hoko.to/apps/ghost) | Site URL, Admin API key, post ID, supported post fields | Create or update one supported content record | Recipe. Ghost Content API is read-only; Admin fields require separate mapping | [Admin API](https://ghost.org/docs/admin-api/), [Content API](https://ghost.org/docs/content-api/) | | [Stripe](https://help.hoko.to/apps/stripe) | Merchant account, restricted test API key, payment metadata, payment and refund IDs | Map one payment through metadata and verify its refund adjustment | Connection. The first adapter is merchant-owned and test-mode only. Stripe Connect is outside this path | [Events](https://docs.stripe.com/api/events/types), [signatures](https://docs.stripe.com/webhooks/signatures) | | [GA4](https://help.hoko.to/apps/ga4) | Property ID, measurement ID, API secret, event ID, consent state | Export a measured click event | Recipe. Measurement Protocol supplements tagging and needs consent handling | [Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/ga4) | | [Google Tag Manager](https://help.hoko.to/apps/google-tag-manager) | Customer-imported fixed `https://hoko.to/analytics.js`, `explicitAnalyticsConsent: true`, CMP state | Add the reviewed browser tag recipe after the CMP gate | Recipe. No provider credential, embedded click, server key, or analytics event send. The ordinary script only persists an existing `hoko_id` from the query or cookie | [Sandboxed JavaScript API](https://developers.google.com/tag-platform/tag-manager/templates/api) | | [PostHog](https://help.hoko.to/apps/posthog) | Project, API key, event ID, consent state | Export a measured click event | Recipe. Requires the canonical `link.clicked` event contract | [API](https://posthog.com/docs/api) | | [Segment](https://help.hoko.to/apps/segment) | Workspace, source write key, event ID, consent state | Export a measured click event | Recipe. Requires the canonical event and consent contract | [HTTP API](https://segment.com/docs/connections/sources/catalog/libraries/server/http-api/) | | [Slack](https://help.hoko.to/apps/slack) | Workspace, OAuth grant, channel ID, message ID | Send a link or campaign notification | Recipe. Notification recipe only; no active native connection yet | [Authentication](https://api.slack.com/authentication) | | [Microsoft Teams](https://help.hoko.to/apps/microsoft-teams) | Tenant, workflow webhook, channel or chat target, event ID | Send a notification through a current Workflow | Recipe. Use Workflows; retired Office 365 Connectors are excluded | [Workflow webhook](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-workflow-webhook) | | [Notion](https://help.hoko.to/apps/notion) | Workspace, integration token or OAuth grant, page and database IDs | Write a link or campaign report | Recipe. Page access must be explicitly granted by the workspace | [Authorization](https://developers.notion.com/guides/get-started/authorization) | | [Airtable](https://help.hoko.to/apps/airtable) | Workspace, base and table IDs, PAT, record ID | Write a link or campaign report | Recipe. Use scoped PATs and preserve base ownership boundaries | [Personal access tokens](https://support.airtable.com/docs/creating-personal-access-tokens) | | [Google Sheets](https://help.hoko.to/apps/google-sheets) | Spreadsheet and tab IDs, OAuth grant, range, row ID | Append a link or campaign report row | Recipe. Spreadsheet access and row reconciliation require proof | [Authorization](https://developers.google.com/sheets/api/guides/authorizing) | The catalog distinguishes manual recipes from native provider connections and public distribution. Use the documented account permissions and current availability. A private recipe does not imply a native connection or marketplace listing. ## Setup guides This section keeps host-specific transport and credential reference. Follow each Help guide for the connection steps. OAuth hosts use their registered client settings; API-key clients use a scoped key from **Dashboard → Integrations → API Keys**. ### ChatGPT [User guide](https://help.hoko.to/apps/chatgpt) ChatGPT acts as an OAuth client of Hoko's authorization server. Its MCP resource is `https://mcp.hoko.to`. The host supplies client registration, the callback, and PKCE parameters. Hoko validates the resource, workspace grant, operation scopes, token refresh, and revocation. Private connectors require an eligible ChatGPT account and a registered Hoko deployment. Registration and client authentication depend on that deployment; a public marketplace listing is a separate distribution step. Follow the Help guide for the browser connection flow. ### Claude [User guide](https://help.hoko.to/apps/claude) Claude web and Claude Desktop use the Hoko MCP resource and OAuth authorization server. Claude owns its client registration, callback, and PKCE parameters; Hoko binds approved scopes to the selected workspace. Client authentication follows the configured deployment. Private connector availability depends on the Claude account; public distribution is separate. Follow the Help guide for account linking. See [Anthropic custom connectors](https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp) for the host fields. ### Claude Code [User guide](https://help.hoko.to/apps/claude-code) Add a remote HTTP MCP server with the CLI. Claude Code sends the header to Hoko for each request. ```sh claude mcp add --transport http hoko https://mcp.hoko.to \ --header "Authorization: Bearer " ``` See [Claude Code MCP setup](https://docs.anthropic.com/en/docs/claude-code/mcp) for the command and OAuth behavior. ### Cursor [User guide](https://help.hoko.to/apps/cursor) Add this entry to the project `.cursor/mcp.json` file. Use the host's secret interpolation for the key. ```json { "mcpServers": { "hoko": { "url": "https://mcp.hoko.to", "headers": { "Authorization": "Bearer ${env:HOKO_API_KEY}" } } } } ``` See [Cursor MCP setup](https://cursor.com/docs/mcp) for the current configuration format. ### VS Code [User guide](https://help.hoko.to/apps/vscode) Add an HTTP server and a password input to `.vscode/mcp.json` or the workspace MCP settings. ```json { "servers": { "hoko": { "type": "http", "url": "https://mcp.hoko.to", "headers": { "Authorization": "Bearer ${input:hoko-api-key}" } } }, "inputs": [ { "type": "promptString", "id": "hoko-api-key", "description": "Hoko API key", "password": true } ] } ``` See [VS Code MCP configuration](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) for HTTP, OAuth, and secret input fields. ### GitHub Copilot [User guide](https://help.hoko.to/apps/copilot) Add Hoko as a remote HTTP MCP server in Copilot Chat or Copilot CLI. In Copilot CLI, the equivalent command is: ```sh copilot mcp add --transport http \ --header "Authorization: Bearer " \ hoko https://mcp.hoko.to ``` Organization policy can disable remote MCP. Follow the host's current setup screen when the command is unavailable. See [GitHub Copilot CLI MCP setup](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) for the command and header order. ### Gemini CLI [User guide](https://help.hoko.to/apps/gemini-cli) Gemini CLI remains a supported Hoko MCP host for Gemini Code Assist Standard or Enterprise users and paid Gemini or Gemini Enterprise Agent Platform API keys. Consumer/free, Google AI Pro, and Google AI Ultra Gemini CLI access stopped serving requests on 2026-06-18. Google directs those users to Antigravity CLI. Antigravity CLI is a separate client. Hoko has not verified its MCP transport, authentication, or feature parity, so this guide does not claim Antigravity support. Add an HTTP server to Gemini CLI settings. Replace the placeholder with your Hoko API key in your local settings file. Gemini documents environment expansion for server `env` values, not for HTTP header values. Keep the settings file private and do not commit it. ```json { "mcpServers": { "hoko": { "httpUrl": "https://mcp.hoko.to", "headers": { "Authorization": "Bearer " } } } } ``` See [Gemini CLI MCP setup](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/mcp-setup.md) for the `httpUrl` and header fields. ### Windsurf [User guide](https://help.hoko.to/apps/windsurf) Add this server to Windsurf's MCP configuration. Windsurf uses `serverUrl` for a remote server. ```json { "mcpServers": { "hoko": { "serverUrl": "https://mcp.hoko.to", "headers": { "Authorization": "Bearer ${env:HOKO_API_KEY}" } } } } ``` See [Windsurf Cascade MCP configuration](https://docs.windsurf.com/windsurf/cascade/mcp) for the host fields and supported remote transports. ### Zapier [User guide](https://help.hoko.to/apps/zapier) Open the Zapier MCP Client connection form. Choose a remote Streamable HTTP server, enter `https://mcp.hoko.to`, choose bearer authentication, and store the API key in the connection secret field. See [Zapier's remote MCP Client guide](https://help.zapier.com/hc/en-us/articles/38777069364109-Connect-remote-MCP-servers-to-Zapier-using-MCP-Client) for the connection fields. ### n8n [User guide](https://help.hoko.to/apps/n8n) Use the [private n8n node guide](https://docs.hoko.to/integrations/n8n) for `Create Link` and exact `externalId` lookup. The node uses an API-key credential and calls `https://api.hoko.to`. This is a private, self-hosted package; n8n Cloud and community publication are not included. You can also use n8n's MCP Client or HTTP Request node. Set the URL to `https://mcp.hoko.to` for MCP, or call the REST operation routes with an `Authorization: Bearer ` header. Keep the key in n8n credentials. See [n8n's MCP Client documentation](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-langchain.mcpclient/) for the node and credential fields. ### Make [User guide](https://help.hoko.to/apps/make) Use the [private Make actions guide](https://docs.hoko.to/integrations/make) for `Create Link` and exact `externalId` lookup. For other operations, use Make's HTTP module with the unversioned Hoko route, add `Authorization: Bearer `, and store the key in a Make connection or secret variable. Make is documented here as a REST client, not as a native Hoko MCP host. See [Make's HTTP OAuth guide](https://help.make.com/connect-to-any-web-service-using-oauth-20) for the connection fields. ### Custom MCP client [User guide](https://help.hoko.to/apps/custom-mcp) Configure Streamable HTTP with the canonical endpoint and bearer header: ```json { "url": "https://mcp.hoko.to", "headers": { "Authorization": "Bearer " } } ``` ### Custom API client [User guide](https://help.hoko.to/apps/custom-api) Call the unversioned resource REST routes with the API key: ```sh curl https://api.hoko.to/integrations/apps \ -H "Authorization: Bearer " \ -H "Accept: application/json" ``` Use the same header for other Hoko operations. The OpenAPI document lists request and response schemas. See the dedicated [Custom API guide](https://docs.hoko.to/custom-api) for client setup and resource route examples. ## Catalog and connections The Apps catalog contains reviewed provider metadata, channel information, availability, and setup guidance. An unavailable card is not an active integration and does not create a database record. The connections API returns only grants that the signed-in human owns for the selected workspace. It includes the grant ID, verified client name, resource, scope labels, workspace, creation time, and effective status. It never returns access or refresh secrets. API keys cannot read or manage human OAuth grants. A workspace administrator cannot inspect another person's connections. A registered grant with no current catalog card remains visible to its owner. ## Connection states | State | Meaning | | ----------- | ---------------------------------------------------------------------------------------------- | | `pending` | The grant exists, but no credentials have been issued. | | `connected` | The grant is valid. A refreshable access token can remain connected after access-token expiry. | | `revoked` | Hoko invalidated the grant and its access and refresh credentials. | | `expired` | The grant or its credentials no longer pass authorization checks. | Token expiry alone does not delete an authorization grant. Membership and client validity also affect the effective state. ## OAuth host flow The external host starts authorization and creates its own state and PKCE verifier. Hoko authenticates the human, shows the workspace and requested scopes, and issues a grant only after explicit consent. The Apps dashboard can show setup instructions. It must not fabricate a callback URL, OAuth state, verifier, or connected account. Reconnecting starts a fresh consent flow. Changing workspaces requires a new grant. Protected MCP calls use the registered OAuth resource and scope metadata. A host that needs account linking receives the standard OAuth challenge. Credentials stay outside tool arguments. ## Disconnect Removing Hoko access from one connection revokes that grant and its access and refresh credentials. Other devices, API keys, and independent grants remain active. Removing Hoko access does not delete an external host's past conversations or uninstall its application. The dashboard action is **Remove Hoko access**. ## Direct resource routes Use these unversioned resource routes: ```http GET /integrations/apps GET /integrations/apps/connections DELETE /integrations/apps/connections/{grantId} ``` The engine operation names are part of the adapter and MCP contracts. The CLI reaches the same engine after browser login and workspace selection: ```bash hoko auth login hoko apps connections hoko apps disconnect --grant-id ``` Personal connection reads and removal require a Session Cookie or Human Token. API keys and delegated OAuth credentials cannot list or manage personal Apps grants. ## Direct API and rate limits Use [API authentication](https://docs.hoko.to/authentication) for API keys and human access tokens. Use [API rate limits](https://docs.hoko.to/rate-limits) to implement retry behavior. Respect `Retry-After` on `429` responses and check whether a write completed before retrying it. Use the [OpenAPI document](https://api.hoko.to/openapi.json) for request and response schemas. The API is unversioned and keeps the existing resource paths. ## Availability An app card reports the current setup path and its requirements. Manual setup, host registration, provider approval, callback deployment, tool review, and public listing are separate steps. Availability does not grant additional permissions. --- ### Automation recipes Create Hoko links from customer-owned automation systems with durable mappings and safe reconciliation. Docs URL: https://docs.hoko.to/integrations/automation Markdown: https://docs.hoko.to/integrations/automation/README.md ## What this guide covers This guide describes the customer-owned automation recipe used by Zapier, Make, n8n, or Power Automate. The platform runs the workflow and calls Hoko's resource REST API. No dedicated Hoko job runner, queue, scheduler, or background service is required. Use the [automation example](https://github.com/Alja7dali/bou.nc/tree/master/examples/automation) to understand the mapping contract. Its Bun command and SQLite ledger are an optional standalone reference. Platform connectors use their platform's persistent state and secret store. The example never reads or writes Hoko tables and does not create a native provider connection or claim marketplace availability. If you choose the standalone reference, run it with these values: ```sh HOKO_API_URL=https://api.hoko.to \ HOKO_API_KEY=... \ HOKO_COLLECTION_ID=... \ HOKO_ACCOUNT_IDENTITY=... \ HOKO_FOREIGN_RECORD_ID=... \ HOKO_DESTINATION=https://example.com/landing \ bun examples/automation/src/recipe.ts ``` The standalone reference stores its SQLite ledger locally. Keep the API key outside source control and keep provider account identities stable across runs. ## Authenticate the Hoko call Create a scoped Hoko API key and store it in the automation platform's secret store. Send it as a bearer header to `https://api.hoko.to`. ```http Authorization: Bearer ``` Use the unversioned resource routes. Do not add an API prefix or gateway prefix: ```http GET https://api.hoko.to/usage GET https://api.hoko.to/links?externalId= POST https://api.hoko.to/links GET https://api.hoko.to/links?id= ``` The API key authenticates the caller and selects its workspace. Do not send a workspace hint header or ask an operator to copy a workspace ID. Call GET /usage before creating a local intent or writing a link. That preflight checks the required usageRead scope. Link reads require linksRead and link writes require linksWrite. Engine operation names such as usage.get and links.createFromApi remain internal metadata for the CLI and MCP adapters. A provider credential, such as a social or CRM API key, stays in that provider's customer-owned connection. For the request and response fields, use the [Custom API guide](https://docs.hoko.to/custom-api) and the [OpenAPI document](https://api.hoko.to/openapi.json). ## Keep one mapping per external record Store a durable intent before a non-idempotent create. Use this identity: ```text (workspaceId, provider, accountIdentity, foreignRecordId) ``` Store the payload fingerprint, request ID, status, and returned Hoko link ID. Pass this bounded, namespaced value as Hoko `externalId`. Verify the returned link against `workspaceId` and the exact namespaced `externalId` before marking the intent `created`. Use this format: ```text hoko:automation::: ``` Keep the value at or below 255 characters. The reference recipe appends a SHA-256 suffix when the encoded value is longer. The mapping belongs to the customer-owned recipe. It is not a Hoko idempotency key and it does not change Hoko's existing create operation. ## Reconcile before retrying The create operation does not promise request idempotency. If a timeout, transport error, or ambiguous response occurs, do not send another create request. Look up the exact `externalId` first. Return `operator-reconciliation-required` when the mapping is missing, the payload changed, or the previous write may have reached Hoko. Let an operator inspect the Hoko link and update the local ledger. Custom slugs are unsupported. The recipe may inspect GET /links?id=... to detect an existing conflict, then rejects the request. It never accepts a free slug, creates one, or chooses a replacement. It only uses POST /links for writes and never retries a write automatically. Use these outcomes: - `created`: Hoko returned a link and the workspace and external ID checks passed. - `already-mapped`: the durable mapping and exact Hoko lookup agree. - `operator-reconciliation-required`: the write result needs a human decision. - `conflict`: the mapping is ambiguous or the input is unsupported. - `denied`: the key is invalid or lacks the required scope. - `rate-limited`: Hoko returned `429`; respect `Retry-After` and inspect the mapping before any later attempt. ## Rate limits and safe logs Keep Hoko request IDs and rate-limit headers in structured, redacted diagnostics. Do not log API keys, provider credentials, customer secrets, full destination query strings, or raw webhook bodies. Bound each request to the automation platform's request budget. A pending local intent is evidence for reconciliation, not permission to create another link. Use a disposable local Hoko database for acceptance tests. Test the GET /usage preflight, account separation, namespaced ID length handling, a changed payload, a rejected custom slug, insufficient scope, revoked key, rate limit, timeout, and cleanup. Do not use staging or production records as fixtures. --- ### Receive link.created webhooks Verify Hoko link.created deliveries and record durable, minimized receipts. Docs URL: https://docs.hoko.to/integrations/link-created Markdown: https://docs.hoko.to/integrations/link-created/README.md ## What this guide covers This guide covers a customer-owned HTTPS receiver for Hoko's `link.created` event. Use the [receiver example](https://github.com/Alja7dali/bou.nc/tree/master/examples/webhooks) as the reference source. The receiver calls no Hoko database and does not create a second webhook contract. The receiver must bind the configured endpoint and `workspaceId` to the event. A provider or automation platform may call the receiver only after it has been configured through the existing Hoko webhook flow. ## Configure the receiver Create the pending webhook in Hoko first. Select `link.created`, enter the receiver's public HTTPS URL, and copy the endpoint ID, workspace ID, and one-time signing secret into server-side environment variables. Then start the receiver and select **Verify webhook** in Hoko. Hoko sends the signed `endpoint.verification` challenge only after the endpoint exists. The reference server uses these variables: ```sh HOKO_ENDPOINT_ID= \ HOKO_WORKSPACE_ID= \ HOKO_WEBHOOK_SECRET=whsec_... \ HOKO_RECEIPTS_DB=./var/hoko-webhook-receipts.sqlite \ bun run src/main.ts ``` After verification succeeds, create one link in the same workspace. Inspect the redacted receipt, then use Hoko's explicit resend action to confirm that a repeated event returns a duplicate receipt. Do not create the link before endpoint verification. ## Verify the raw request Read the exact request bytes before parsing JSON. The sender supplies: ```http webhook-id: webhook-timestamp: webhook-signature: v1, ``` Compute HMAC-SHA256 over: ```text webhook-id + "." + webhook-timestamp + "." + exact_raw_body ``` Use the configured `whsec_` secret and compare equal-length signatures with a timing-safe comparison. Reject a missing header, malformed timestamp, invalid signature, or body larger than 64 KiB. Accept timestamps only within 300 seconds of the receiver clock. Verify the body `id` equals `webhook-id`, the body `type` is `link.created`, and `data.workspaceId` equals the configured workspace. Verify the endpoint ID before processing an endpoint challenge. ## Store a minimized receipt After signature, endpoint, workspace, and schema checks pass, write one durable receipt keyed by `(workspaceId, webhook-id)`. Store the event ID, raw-body SHA-256 digest, request ID, endpoint ID, event type, and received time. Keep the receipt small. Do not store the raw body, signature, secret, customer data, destination query, or full response. Keep a replay ledger for at least the 300-second timestamp window and retain the event ID for the lifetime of the receiver's operational history. A repeated event with the same digest returns `2xx` as a duplicate. The same event ID with a different digest returns a conflict for operator review. Return a `2xx` response quickly after the receipt is durable. The receipt proves that the receiver accepted the event. It does not prove that a later business action completed. ## Delivery states and resend Hoko sends one bounded request-time attempt and records `pending`, `failed`, or `unknown` outcomes when the attempt cannot finish with a final result. Hoko does not run an automatic background worker and does not promise exactly-once delivery. Treat `unknown` as possibly delivered. Deduplicate by `webhook-id` before applying any side effect. An operator may use the existing explicit resend action after inspecting the receipt. A resend has a new signature timestamp but keeps the event identity, so the receiver must remain idempotent. ## Local acceptance Use a disposable receiver and local Hoko database. Test valid and invalid signatures, a stale timestamp, a replay, a body-size rejection, a wrong workspace, a wrong endpoint, a malformed event, and concurrent duplicate delivery. Record only redacted receipts and request IDs. --- ### Google Tag Manager attribution template Import Hoko's customer-owned browser attribution template with explicit consent. Docs URL: https://docs.hoko.to/integrations/google-tag-manager Markdown: https://docs.hoko.to/integrations/google-tag-manager/README.md ## What this guide covers This is a customer-imported Google Tag Manager custom template. It loads the fixed public script `https://hoko.to/analytics.js` after an explicit consent gate. It is a recipe, not a native Google OAuth connection or a template gallery listing. [Download the template](https://docs.hoko.to/integrations/google-tag-manager/template.tpl) or inspect the [template source](https://github.com/Alja7dali/bou.nc/tree/master/examples/google-tag-manager). Keep the file in the customer-owned container workflow. Hoko has not verified a provider container or published this template to a gallery. ## Configure consent Set the required template input to: ```text explicitAnalyticsConsent: true ``` Map that boolean to the site's consent management platform. The template fails closed for `false`, an unset value, or any non-boolean value. Do not treat an unset GTM consent type as explicit consent. The template requests only GTM's sandboxed script injection permission. It does not request a provider credential, cookie access, local-storage access, global reads, data-layer reads, or server network access. ## Load the fixed script The template injects exactly: ```text https://hoko.to/analytics.js ``` The ordinary script reads an existing `hoko_id` from the current query or cookie and persists that identifier. It does not create an embedded click, send analytics events, or expose a second click identifier. Keep the separate `/{shortId}/analytics.js` embedded-click capability out of this template. ## Import and preview Import the file into a customer-owned GTM container. Preview the tag with consent denied, consent unset, consent granted, and no existing `hoko_id`. Check that the fixed URL is the only script loaded and that repeated firing does not create another click. Publishing requires the customer's container approval and remains an external verification gate. Do not report the template as provider-verified until an authorized disposable GTM container records import, Preview, consent, repeat-fire, and cleanup evidence. See GTM's [sandboxed JavaScript API](https://developers.google.com/tag-platform/tag-manager/templates/api) and [template permissions](https://developers.google.com/tag-platform/tag-manager/templates/permissions) for the host contract. ## Remove the template Remove the template and its tags from the customer-owned container, then restore the previous container state. The Hoko public script and existing cookie behavior remain unchanged. --- ### Power Automate Import the private Hoko connector and create links from a Power Automate flow. Docs URL: https://docs.hoko.to/integrations/power-platform Markdown: https://docs.hoko.to/integrations/power-platform/README.md ## Download the preview connector The connector runs in Power Automate, Power Apps, or Copilot Studio and calls Hoko's existing API. No dedicated Hoko job runner is required. Local REST checks pass; Microsoft import and workflow execution still need verification in an authorized disposable environment. This is an actions-only private preview, without marketplace listing. - [OpenAPI 2.0 definition](https://docs.hoko.to/integrations/power-platform/apiDefinition.swagger.json) - [Connection properties](https://docs.hoko.to/integrations/power-platform/apiProperties.json) - [Source and acceptance instructions](https://github.com/Alja7dali/bou.nc/tree/master/integrations/power-platform) Microsoft currently requires OpenAPI 2.0 and a definition smaller than 1 MB. This export is generated from Hoko's canonical contract; it introduces no new API version. See [Microsoft's connector FAQ](https://learn.microsoft.com/en-us/connectors/custom-connectors/faq). ## Create a connection 1. Create a custom connector from the definition in your Power Platform environment. 2. Import the connection properties if your tooling supports that file. 3. Create a connection with a Hoko API key that has `linksRead` and `linksWrite`. The secure connection sends `X-API-Key` to `https://api.hoko.to`. The key selects the Hoko workspace and permitted collections. There is no workspace override, session cookie, or human token field. Keep the key in the connection, outside flow payloads and logs. Use disposable local Hoko fixtures for tests. Staging, production, and Playground are not disposable databases. A cloud flow needs an explicitly authorized reachable fixture before it can run acceptance checks. ## Create one link and find it Use the create action with an array containing one item: ```json [ { "url": "https://example.com/product", "collectionId": "", "externalId": "hoko:automation:power-automate::" } ] ``` It calls `POST https://api.hoko.to/links`. The response is an array of links with `id`, `shortUrl`, and `externalId`. Use the lookup action with the exact same `externalId`; it calls `GET https://api.hoko.to/links?externalId=...`. Check that exactly one link matches and keep its Hoko ID in the flow's mapping store. The [automation guide](https://docs.hoko.to/integrations/automation) defines the bounded external ID and mapping contract. Full request fields remain in [Hoko's OpenAPI document](https://api.hoko.to/openapi.json). ## Receive link-created events The native connector remains actions-only. Microsoft's webhook trigger requires a registration response with a provider-managed `Location` cleanup value. Hoko's current `POST /webhooks` response returns the endpoint in JSON and does not return that header, so the OpenAPI export does not advertise an unverified native trigger. Use the customer-owned receiver bridge in `integrations/power-platform/src/power-platform-webhook.ts` when a flow needs events. Create and verify a Hoko webhook through the existing API, deploy the bridge at the callback URL, and forward only verified events to a Power Automate HTTP flow. The bridge checks raw bytes, signature, timestamp, event ID, event type, and workspace ID, then deduplicates replays. Hoko runs no worker. Microsoft import and flow receipt remain provider acceptance gates. Use `integrations/power-platform/power-automate-http-flow.template.json` for the flow shape. Require the 32-byte `x-hoko-relay-auth` secret and the per-event relay HMAC headers before mapping fields. The local loopback rehearsal accepts a verified event and rejects a forged body. ## Prevent duplicate writes Set the create action's retry policy to **None**. Use one serialized flow as the exclusive owner of each mapping. Persist a prepared intent, payload fingerprint, and request ID in a durable store before sending the create request. A connector definition alone does not supply that store or enforce serialization. After a timeout or uncertain response, use the external ID lookup. Do not send another create request automatically. Missing or multiple matches, changed input, or an unresolved prior intent require operator reconciliation. Keep the intent when execution fails; deleting it permits duplicate writes. Hoko still enforces scopes and rate limits through the shared engine. Preserve `X-Request-Id`, the `X-RateLimit-*` headers, and `Retry-After` for support and scheduling. Treat `401` and `403` as a connection or permission issue. Respect `429` and reconcile before any later write. ## Remove the preview Remove the test flow, connector, connection, and owned fixture records, then revoke its temporary Hoko key. Provider import, connection, create, lookup, denial cases, and cleanup must be recorded before this connector is called verified. --- ### Zapier Run the private Hoko link actions in Zapier with API-key authentication. Docs URL: https://docs.hoko.to/integrations/zapier Markdown: https://docs.hoko.to/integrations/zapier/README.md ## Get the private app preview The Zapier app runs in Zapier and calls Hoko's unversioned resource REST API. It needs no dedicated Hoko job runner, queue, scheduler, or background service. - [Automation contract](https://docs.hoko.to/integrations/automation) - [Zapier Platform](https://docs.zapier.com/platform) - [Download the app bundle](https://docs.hoko.to/integrations/zapier/index.cjs) - [Download package metadata](https://docs.hoko.to/integrations/zapier/package.json) The package is a private preview. A Zapier import, connection, workflow run, and marketplace review remain external acceptance work. ## Configure the connection Create a Hoko API key with `linksRead`, `linksWrite`, `webhooksRead`, and `webhooksWrite`. Store it in Zapier's secret connection field. Use `https://api.hoko.to` as the Hoko origin. The API key selects one Hoko workspace. The connection test calls `GET /links?take=1`. The app does not expose a workspace ID field. Hoko binds each operation to the workspace selected by the key. ## Use the actions The private preview exposes two actions: | Action | Required values | Resource route | Engine metadata | | ----------- | ------------------------------------------- | -------------- | --------------- | | Create Link | Collection ID, Destination URL, External ID | `POST /links` | `links.createFromApi` | | Find Link | External ID | `GET /links?externalId=...` | `links.list` | Pass a stable source record ID as `External ID` to `Create Link`. The field is required. Use the same exact value in `Find Link`. Keep the value namespaced and at or below 255 characters. The create response contains the Hoko link ID, short URL, destination URL, collection ID, and external ID. The lookup reads a list, filters it to exact external ID matches, and returns one item to Zapier only when exactly one match exists. Zero matches return no item. Multiple matches fail for operator review. Successful action output also includes `requestId`. When Hoko sends valid rate headers, it includes `rateLimit` with `limit`, `remaining`, and `resetAt`. Errors include a safe `requestId`; rate-limited errors may include `Retry-After`. Malformed rate values are omitted. ## Signed event triggers (activation blocked) The private preview exposes REST hook triggers for `link.created` and `sale.created`. Enter the public Workspace ID from Hoko Settings, a pre-enrolled active relay endpoint ID, and its exact HTTPS relay URL. The API key must belong to that workspace. Keep the Hoko webhook signing secret in the private connection secret field; it is never returned in trigger output. The callback verifies the exact raw request body, `webhook-id`, timestamp, and HMAC before returning one item. It checks the event ID, event type, and workspace ID against the subscription. Zapier uses the stable event ID for retry deduplication. The delivery model is bounded and at-least-once. Hoko does not promise exactly-once delivery. The trigger output contains the shared envelope fields: event ID, event type, created time, event data ID, and workspace ID. The adapter does not add sale amounts or other private fields that are absent from the signed envelope. Subscribe and unsubscribe verify endpoint ownership, event selection, name, and URL binding before deleting the endpoint. Scope failures, revoked keys, rate limits, disabled endpoints, invalid signatures, stale timestamps, and binding mismatches return safe errors with request IDs. Activation has a callback contract gap. Zapier Platform Core 19.2.0 requires a REST hook `perform` function to return an item array and provides no raw HTTP response override. Hoko verification requires the exact `{"challenge":"..."}` JSON response, so the direct callback cannot activate an endpoint through `webhooks.verify`. Keep the preview private and actions-only until the customer-owned relay contract is pre-enrolled and wired to the subscription path. The relay must answer the challenge, preserve exact signed bytes and headers when forwarding to Zapier, durably deduplicate event IDs, and enforce bounded enrollment, revocation, and rate handling. It must not weaken HMAC verification or add an Hoko worker. ## Reconcile before retrying Link creation has no request idempotency guarantee. The caller must store the source account, foreign record ID, payload fingerprint, request ID, and returned Hoko link ID in durable workflow state. The action checks the exact external ID before creating, then verifies the returned link with the same lookup. If the create acknowledgement is lost, it performs one safe read by the exact external ID. It reports a created link only when exactly one result matches the external ID, destination, and collection. An empty or duplicated result, a malformed read, or a network error returns a halted outcome for operator reconciliation. The action never sends a second create. Zapier does not provide Hoko's mapping or serialization policy. Make the workflow the exclusive owner of each source mapping and disable automatic replay where the host allows it. The app sends one request ID per Hoko operation. It does not follow redirects, limits each request to 10 seconds and 1 MB, and preserves bounded rate metadata. Treat `401` as an invalid key, `403` as a missing scope, and `429` as a rate limit. Respect `Retry-After`. Keep request IDs and rate-limit headers in redacted logs. ## Keep the preview private The first app slice excludes analytics, API-key management, billing, profile uploads, destructive workspace actions, and public directory publication. Zapier's remote MCP Client remains a separate manual connection path. Use disposable local Hoko fixtures for acceptance. Do not use production, staging, or Playground as a test database. Record the provider import, connection test, create, exact lookup, denied scope, revoked key, rate-limit response, ambiguous write handling, and cleanup before calling the app verified. --- ### Make Run Hoko's private link actions and link.created trigger in Make. Docs URL: https://docs.hoko.to/integrations/make Markdown: https://docs.hoko.to/integrations/make/README.md ## Use the private app The Hoko Make app runs inside Make and calls Hoko's unversioned resource REST API. It needs no dedicated Hoko job runner, queue, scheduler, or background service. The app is private. Make import, connection, scenario execution, and provider review remain external acceptance work. Download the repository editor bundle: [hoko.private-app.json](https://docs.hoko.to/integrations/make/hoko.private-app.json). The file is generated from Hoko's source and is not a native Make one-click import or export file. Map `base`, `connection`, and each module's parameters, communication, and output fields into the matching Make editor sections. Select the saved Hoko connection on every module. ## Configure the connection Create a Hoko API key in **Dashboard → Integrations → API Keys**. Store it in Make's secure connection field. Use `https://api.hoko.to` as the Hoko origin. The key selects one Hoko workspace. Do not add a workspace ID to a module. When you create each Make module, select the saved **Hoko API key** connection in the module's connection field. The bundle metadata does not bind a Make host connection automatically. Follow [Make's custom-app setup](https://www.make.com/en/how-to-guides/build-custom-app-in-make), step 6. The connection test and `Find Link` require `linksRead`. `Create Link` also requires `linksWrite`. ## Use the actions | Action | Required values | Resource route | Engine metadata | | ----------- | ------------------------------------------------------- | -------------- | --------------- | | Create Link | Destination URL, Collection ID, External ID, Request ID | `POST /links` | `links.createFromApi` | | Find Link | External ID, Request ID | `GET /links?externalId=...` | `links.list` | Pass a stable, namespaced source record identity as `External ID`. Keep it at or below 255 characters. Pass a required correlation `Request ID` at or below 128 characters. Use the exact same external ID for `Find Link`. `Create Link` sends one raw create request. It does not check for an existing mapping or read the result again. Surround the action with a durable prepared intent, an exact lookup, and readback in one serialized scenario owner. `Find Link` requests two matches and returns a wrapper with `matches`, `matchCount`, `requestId`, and `rateLimit`. The scenario handles zero, one, or two matches. Before creating a link, call `GET https://api.hoko.to/collections` with the same connection. Copy the returned collection ID into `Collection ID`. Resolve previously saved collection references through this lookup before writing a new mapping. ## Set the scenario controls Configure the Make scenario with these values: | Setting | Value | Purpose | | --------------------------- | ------- | ----------------------------------------------------- | | Process data in order | **On** | Gives each mapping one exclusive scenario owner. | | Store incomplete executions | **Off** | Prevents incomplete runs from being saved for replay. | | Commit after each module | **On** | Commits the prepared intent before the Hoko write. | Make normally commits at the end of a scenario. If a later module or timeout fails, that behavior can roll back the prepared intent. It does not undo a link that Hoko already created. Do not add a Retry error handler around `Create Link`. Automatic completion belongs to the Retry error handler; it is not a global scenario setting. For personal data, you may enable **Keep data confidential**. Make describes that option as a privacy recommendation. It does not guarantee that data is absent from provider logs. See [Make scenario settings](https://help.make.com/scenario-settings). Successful output includes the Hoko link identity, short URL, destination URL, collection ID, external ID, and request ID. Valid rate headers produce bounded `rateLimit` metadata with `limit`, `remaining`, and `resetAt`. ## Handle retries Link creation has no idempotency guarantee. Disable automatic retry for incomplete executions and do not add a retry error handler around `Create Link`. Do not retry after a timeout, malformed response, or lost acknowledgement. Look up the exact external ID before any later write. Keep a prepared intent, source account, foreign record ID, payload fingerprint, request ID, and returned Hoko link ID in Make scenario state. Treat `401` as an invalid or revoked key, `403` as a missing scope, and `429` as a rate limit. `Create Link` maps `429` and `5xx` responses to runtime errors, because Make's rate-limit error class can trigger automatic retries. Honor `Retry-After`. Keep request IDs and rate metadata in redacted logs. ## Watch Link Created Add **Hoko → Watch Link Created** as the first module in a Make scenario. Make creates a dedicated webhook. Hoko binds that endpoint to the API-key workspace and the `link.created` event. The customer-owned relay returns Hoko's verification challenge and deletes the owned endpoint when the Make webhook is detached. The trigger emits `id`, `type`, `created`, `data.id`, and `data.workspaceId`. Hoko sends no destination URL or API key in this event. Make custom-app IML receives a parsed body. It does not preserve the exact raw bytes required to verify Hoko's HMAC signature. Do not send production events directly to the Make URL. Place a customer-owned HTTPS receiver between Hoko and Make. That receiver must verify the raw-body signature, reject bodies over 64 KiB and timestamps outside 300 seconds, durably deduplicate `webhook-id`, and forward only verified JSON to Make. Hoko delivery remains bounded and does not guarantee exactly-once execution. ## Keep the app private This slice excludes analytics, API-key management, billing, profile uploads, destructive workspace actions, OAuth, MCP, and public Make distribution. Use disposable local Hoko fixtures for acceptance. Do not use production, staging, or Playground as a test database. Record the Make app revision, scenario export, successful read and write, denied scope, revoked key, rate limit, uncertain-write handling, secret redaction, and cleanup before calling the app verified. --- ### n8n Use Hoko link actions in a private n8n community node. Docs URL: https://docs.hoko.to/integrations/n8n Markdown: https://docs.hoko.to/integrations/n8n/README.md ## Use the private node The Hoko n8n node calls Hoko's unversioned resource REST API and the shared engine. No dedicated Hoko job runner is needed. The preview targets n8n `2.42.x` with Node.js 24. Download the package at [`n8n-nodes-hoko.tgz`](https://docs.hoko.to/integrations/n8n/n8n-nodes-hoko.tgz). For a self-hosted n8n instance, copy the file to the instance and run: ```sh mkdir -p ~/.n8n/nodes cd ~/.n8n/nodes npm install /path/to/n8n-nodes-hoko.tgz ``` Restart n8n after installation. Enable community nodes if your deployment requires that setting. The disposable Hoko engine and native Create and Find workflow and credential proofs passed on n8n `2.42.6` with Node.js `24.19.0`. n8n Cloud installation and execution are not verified. This is not a community listing. ## Configure the credential Create a Hoko API key in **Dashboard → Integrations → API Keys**. Give it `linksRead` and `linksWrite` for `Create Link`. `Find Link` and the credential test need `linksRead`. Store the key in n8n's **Hoko API** credential. The node uses the fixed Hoko origin `https://api.hoko.to`. The key selects the workspace. Do not add a workspace ID or another origin to the node. ## Create and find links `Create Link` accepts a destination URL, collection ID, external ID, and a caller correlation ID. The URL must be HTTP or HTTPS, have no embedded credentials, and stay within 2,048 characters. Resolve the collection ID from `GET /collections`. The external ID stays within 255 characters. Correlation IDs use visible ASCII and stay within 128 characters. Before the first write, call `GET https://api.hoko.to/collections` with the same credential and copy the returned collection ID. Resolve saved collection references through this lookup before creating a new mapping. `Find Link` returns zero, one, or multiple exact external-ID matches. Use the same external ID for a later reconciliation lookup. ## Handle retries Disable **Retry On Fail** on `Create Link`. Link creation is not idempotent. Save the prepared intent before the Hoko write. If the response is uncertain, look up the exact external ID and stop for operator review. Do not retry blindly or replace a conflicting link. Treat `401` as an invalid or revoked key, `403` as a missing scope, and `429` as a rate limit. Respect `Retry-After`. Each HTTP dispatch receives a unique terminal Hoko `requestId`. `Create Link` can make a preflight, write, and readback dispatch. Successful output includes the verification-call `requestId`, the caller's `correlationId`, and that terminal call's validated rate-limit metadata. ## Keep the preview private This slice excludes analytics, API-key management, billing, profile uploads, destructive workspace actions, webhooks, event triggers, OAuth, and public n8n distribution. Existing n8n HTTP Request and MCP Client workflows remain usable. Use disposable PostgreSQL and a disposable self-hosted n8n instance for acceptance. Do not use production, staging, or Playground as a test database. Record the n8n version, package version, credential test, create, exact lookup, denied scope, revoked key, rate limit, uncertain-write handling, secret redaction, and cleanup before calling the node verified. See the [n8n package README](https://docs.hoko.to/integrations/n8n/README.md), [n8n community-node installation](https://docs.n8n.io/integrations/community-nodes/installation/manual-install/), and [n8n node development](https://docs.n8n.io/integrations/creating-nodes/). ## Upgrade or remove the node Keep the previous tarball and an n8n backup before an upgrade. Install the replacement tarball in the self-hosted n8n user directory and restart n8n. Run disposable Create and Find workflows before using the replacement with a real workspace. To roll back, reinstall the previous tarball and restart n8n. Remove temporary workflows and revoke their Hoko keys. Remove the package after no workflow uses it. --- ### Commerce integrations Connect commerce providers to Hoko link attribution through the shared engine. Docs URL: https://docs.hoko.to/integrations/commerce Markdown: https://docs.hoko.to/integrations/commerce/README.md ## What this guide covers Commerce adapters connect a provider product or order to Hoko attribution. The adapter validates provider signatures and tenant ownership, then calls the shared commerce engine. It never writes directly to Hoko analytics tables. Supported planning families are Shopify, Salla, Zid, WooCommerce, BigCommerce, Adobe Commerce, and Stripe. A catalog entry or local adapter does not mean a provider account, app listing, or hosted connection is available. ## Required inputs - provider store or account identifier; - provider OAuth or API credential stored in the provider connection; - product, checkout, order, payment, and refund identifiers as applicable; - webhook signing secret and delivery identifier for event adapters; - Hoko workspace and scoped API access for customer-owned recipes. ## Safe implementation path 1. Choose the provider-specific contract and confirm its account requirements. 2. Install the provider adapter in a disposable account and disposable Hoko database. 3. Create one product link with an external identity. 4. Rehearse one paid event, one duplicate, one refund, and one rejected tenant. 5. Record provider receipts before enabling hosted or public distribution. See the provider package READMEs in [`integrations/`](https://github.com/alja7dali/labdotsa/tree/master/integrations), the [Apps catalog](./apps), and the [automation guide](./automation). --- ### Social and CMS integrations Build reviewable social and CMS recipes around Hoko's shared engine. Docs URL: https://docs.hoko.to/integrations/social-cms Markdown: https://docs.hoko.to/integrations/social-cms/README.md ## Scope The social and CMS recipes cover WordPress, Typefully, Buffer, Publer, Metricool, SocialPilot, Sprout, Webflow, and Ghost. Local recipes produce a provider request and durable reconciliation state. They do not claim that a post was published until a provider receipt exists. ## Required inputs - provider account, workspace, site, or profile; - provider API key, OAuth grant, or customer-owned MCP connection; - Hoko API key with only the scopes used by the recipe; - provider record ID and an idempotency key; - draft or review mode where the provider does not support safe publishing. ## Boundary Provider credentials stay in the provider connection or customer-owned host. The shared Hoko engine handles authentication, authorization, usage, rate limits, link creation, and reconciliation. An uncertain provider write must be reconciled by external identity before retrying. See the [Apps catalog](./apps), [automation guide](./automation), and the social/CMS package README for provider-specific fields. --- ### Reporting integrations Send Hoko link and conversion facts to reporting and campaign systems. Docs URL: https://docs.hoko.to/integrations/reporting Markdown: https://docs.hoko.to/integrations/reporting/README.md ## Providers The reporting recipes cover Slack, Microsoft Teams, Notion, Airtable, Google Sheets, GA4, PostHog, Segment, HubSpot, Salesforce, Klaviyo, Mailchimp, Customer.io, and Brevo. The shared engine normalizes facts and applies tenant, scope, usage, and rate-limit policy before a provider request is built. ## Required inputs - provider workspace, property, base, audience, or account ID; - provider token, OAuth grant, webhook, or ingestion key; - Hoko workspace and scoped API key; - event or campaign identity and a replay-safe external ID; - consent and retention settings for any customer or conversion data. Provider-shaped loopbacks and disposable database rehearsals prove request contracts only. Record a provider response in a disposable account before claiming delivery or campaign acceptance. See the [automation guide](./automation) and [Apps catalog](./apps). --- ### OAuth provider connections Configure provider OAuth connections without bypassing the shared Hoko engine. Docs URL: https://docs.hoko.to/integrations/oauth Markdown: https://docs.hoko.to/integrations/oauth/README.md ## Connection boundary OAuth identifies and authorizes a provider connection. It does not replace Hoko authentication, authorization, usage, or rate limiting. After token exchange, the connection calls the same engine used by Dashboard, REST, CLI, and MCP. Keep client IDs, secrets, redirect URIs, encryption keys, and provider tokens server-side. Bind state, PKCE, workspace, and callback origin before exchanging an authorization code. Revoke and disconnect must prevent later refresh from reactivating a connection. Provider registration, redirect approval, account eligibility, and marketplace review are external gates. A local OAuth contract is not a provider receipt. See the [Apps catalog](./apps) and the provider package README. --- ### Later and Hootsuite Review bounded Later reporting and Hootsuite scheduling contracts. Docs URL: https://docs.hoko.to/integrations/later-hootsuite Markdown: https://docs.hoko.to/integrations/later-hootsuite/README.md ## Current boundary Later Influence reporting and Hootsuite scheduled-message recipes have local contracts and loopback evidence. They remain gated on provider-approved credentials, account eligibility, callback configuration, and disposable provider fixtures. Later reporting does not imply Later social publishing. Hootsuite scheduling does not imply a native Hoko connector or public Apps listing. Keep each provider credential in the customer-owned connection and call Hoko through the shared engine. Before promotion, record account identity, scopes, callback, one successful read/write or scheduled-message receipt, replay behavior, cleanup, and owner. See the [Apps catalog](./apps) and the integration package README. --- ### Introduction Read, update, and delete customer records used for conversion attribution. Docs URL: https://docs.hoko.to/customers/introduction Markdown: https://docs.hoko.to/customers/introduction/README.md ## Overview The Customers API provides access to customer data used for conversion attribution and customer management workflows. Direct customer writes can update or soft-delete existing customers, but this API does not create customers. When you track a lead or sale event using the conversion tracking endpoints (/track/lead or /track/sale), Hoko automatically creates or updates the customer record based on the customerExternalId. This ensures your customer data stays in sync with your conversion tracking activities. Use the Customers API to retrieve customer information, update existing customer profile fields, verify customer existence, build customer management interfaces, or integrate customer data with other systems. The API supports filtering by customer ID or external ID, making it easy to find specific customers. - (GET) Retrieve customers by ID or external ID with pagination support - (PUT) Update existing customers by ID or external ID - (DELETE) Soft-delete customers by ID - Automatic customer creation/updates through conversion tracking endpoints - Support for filtering and sorting to efficiently find specific customers > **Info: Customer Management** > Use `customersRead` for retrieval and `customersWrite` for direct updates or deletion. Customer creation remains part of conversion tracking through the `conversionsWrite` scope. --- ### (GET) Get customers Retrieve customers by ID or external ID. Supports pagination and sorting. Docs URL: https://docs.hoko.to/customers/get Markdown: https://docs.hoko.to/customers/get/README.md ## Endpoint GET /customers Retrieve customers by id or externalId. Supports pagination with take, skip, and sorting by createdAt. Use this endpoint to list your customers, verify customer existence, or build customer management interfaces. **Endpoint** ```text GET /customers ``` ## Authentication Requires an authorized credential with permission for `customersRead`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Query Parameters | Parameter | Type | Required | Location | Description | | ---------- | ------------- | -------- | -------- | ------------------------------------------------------------------------------------------- | | id | string (ULID) | No | query | Filter by specific customer ID. Returns a single customer if found. | | externalId | string | No | query | Filter by external ID. Useful for syncing with external systems. | | take | number | No | query | Number of results to return (default: 50, min: 1, max: 5,000). | | skip | number | No | query | Number of results to skip for pagination (default: 0, min: 0). | | sort | string | No | query | Sort order by createdAt: "asc" for oldest first, "desc" for newest first (default: "desc"). | > **Warning: Request Limits** > The `take` parameter supports values from 1 to 5,000. Requests above 5,000 are rejected. ## Status Codes ### 200 Successfully retrieved customers. **Request** ```bash curl -X GET "https://api.hoko.to/customers?take=50&sort=desc" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/customers?take=50&sort=desc', { method: 'GET', headers: { Authorization: 'Bearer ' } }); const customers = await response.json(); ``` **Response** ```json [ { "id": "", "externalId": "customer_123", "name": "John Doe", "email": "john@example.com", "phone": "+1234567890", "avatar": "https://example.com/avatar.jpg", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` ### 400 Invalid query parameters. This includes invalid ULID filters or invalid `take`, `skip`, or `sort` values. **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X GET "https://api.hoko.to/customers" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/customers', { method: 'GET', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required customersRead scope. **Request** ```bash curl -X GET "https://api.hoko.to/customers" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/customers', { method: 'GET', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["customersRead"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X GET "https://api.hoko.to/customers" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/customers', { method: 'GET', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X GET "https://api.hoko.to/customers?take=50&sort=desc" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/customers?take=50&sort=desc', { method: 'GET', headers: { Authorization: 'Bearer ' } }); const customers = await response.json(); ``` **Response** ```json [ { "id": "", "externalId": "customer_123", "name": "John Doe", "email": "john@example.com", "phone": "+1234567890", "avatar": "https://example.com/avatar.jpg", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` --- ### (PUT) Update customers Update existing customers by ID or external ID. Docs URL: https://docs.hoko.to/customers/put Markdown: https://docs.hoko.to/customers/put/README.md ## Endpoint PUT /customers Update one or more existing customers in a single request. Entries with `id` update that customer. Entries without `id` use `externalId` to find an existing active customer. This endpoint does not create customers. **Endpoint** ```text PUT /customers ``` ## Authentication Requires an authorized credential with permission for `customersWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body The request body must be an array of customer objects. | Parameter | Type | Required | Location | Description | | ---------- | ------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string (ULID) | No | body | Existing customer ID. When provided, the entry updates that customer. | | externalId | string | Yes without id | body | External customer identifier. Without `id`, this identifies the existing customer to update. With `id`, it can update the customer's external ID. | | name | string/null | No | body | Customer display name. Send null to clear. | | email | string/null | No | body | Customer email address. Send null to clear. | | phone | string/null | No | body | Customer phone number. Send null to clear. | | avatar | string/null | No | body | HTTPS avatar image URL. Send null to clear. | Entries with `id` must include at least one mutable field. Entries without `id` must include `externalId` for an existing customer and at least one customer field (`name`, `email`, `phone`, or `avatar`). ## Status Codes ### 200 Customers updated successfully. **Request** ```bash curl -X PUT "https://api.hoko.to/customers" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "externalId": "customer_123", "name": "Jane Doe", "email": "jane@example.com", "avatar": "https://example.com/jane.png" } ]' ``` **Response** ```json [ { "id": "", "externalId": "customer_123", "name": "Jane Doe", "email": "jane@example.com", "phone": null, "avatar": "https://example.com/jane.png", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` ### 400 Invalid JSON, invalid customer IDs, duplicate IDs or external IDs in the request, or a customer that does not belong to the workspace. ### 401 Invalid or missing API key. ### 403 API key does not have the required customersWrite scope. ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. ### 500 Unexpected server error. --- ### (DELETE) Delete customers Soft-delete existing customers by ID. Docs URL: https://docs.hoko.to/customers/delete Markdown: https://docs.hoko.to/customers/delete/README.md ## Endpoint DELETE /customers Soft-delete one or more customers by ULID. Deleted customers are excluded from `GET /customers` and future direct updates. **Endpoint** ```text DELETE /customers ``` ## Authentication Requires an authorized credential with permission for `customersWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body The request body must be an array of customer ULIDs. ```json ["", ""] ``` ## Status Codes ### 200 Customers deleted successfully. **Request** ```bash curl -X DELETE "https://api.hoko.to/customers" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[""]' ``` **Response** ```json { "deletedIds": [""] } ``` ### 400 Invalid JSON, invalid customer IDs, duplicate IDs in the request, or a customer that does not belong to the workspace. ### 401 Invalid or missing API key. ### 403 API key does not have the required customersWrite scope. ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. ### 500 Unexpected server error. --- ### Introduction Create, read, update, and delete partners for attribution tracking and commission management. Docs URL: https://docs.hoko.to/partners/introduction Markdown: https://docs.hoko.to/partners/introduction/README.md ## Overview Partners help track attribution and commission data for affiliate programs, referral systems, and partner marketing campaigns. Associate partners with links to automatically attribute clicks and conversions to the correct partner. Use partners to track which affiliates or referral sources are driving traffic and conversions, calculate commissions, and measure partner performance. Each partner can be associated with multiple links, enabling comprehensive attribution tracking across your marketing channels. The Partners API provides full CRUD operations for managing your partner database. Create partners, update their information, and track their performance through associated links and conversions. - (GET) Retrieve partners with pagination and filtering - (POST) Create one or more partners with contact information - (PUT) Update existing partners or create new ones with upsert - (DELETE) Soft delete partners while preserving attribution data > **Tip: Partner Attribution** > Associate partners with links using the partnerId field when creating or updating links. This enables automatic attribution of clicks and conversions to the correct partner, making it easy to track partner performance and calculate commissions. --- ### (GET) Get partners Retrieve partners by ID. Supports pagination and sorting. Docs URL: https://docs.hoko.to/partners/get Markdown: https://docs.hoko.to/partners/get/README.md ## Endpoint GET /partners Retrieve partners by id. Supports pagination with take, skip, and sorting by createdAt. **Endpoint** ```text GET /partners ``` ## Authentication Requires an authorized credential with permission for `partnersRead`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Query Parameters | Parameter | Type | Required | Location | Description | | --------- | ------------- | -------- | -------- | ------------------------------------------------------------------------------------------- | | id | string (ULID) | No | query | Filter by specific partner ID. Returns a single partner if found. | | take | number | No | query | Number of results to return (default: 50, min: 1, max: 5,000). | | skip | number | No | query | Number of results to skip for pagination (default: 0, min: 0). | | sort | string | No | query | Sort order by createdAt: "asc" for oldest first, "desc" for newest first (default: "desc"). | > **Warning: Request Limits** > The `take` parameter supports values from 1 to 5,000. Requests above 5,000 are rejected. ## Status Codes ### 200 Successfully retrieved partners. **Request** ```bash curl -X GET "https://api.hoko.to/partners?take=50&sort=desc" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners?take=50&sort=desc', { method: 'GET', headers: { Authorization: 'Bearer ' } }); const partners = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Partner Name", "email": "partner@example.com", "phone": "+1234567890", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` ### 400 Invalid query parameters. This includes invalid ULID filters or invalid `take`, `skip`, or `sort` values. **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X GET "https://api.hoko.to/partners" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'GET', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required partnersRead scope. **Request** ```bash curl -X GET "https://api.hoko.to/partners" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'GET', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["partnersRead"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X GET "https://api.hoko.to/partners" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'GET', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X GET "https://api.hoko.to/partners?take=50&sort=desc" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners?take=50&sort=desc', { method: 'GET', headers: { Authorization: 'Bearer ' } }); const partners = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Partner Name", "email": "partner@example.com", "phone": "+1234567890", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` --- ### (POST) Create partners Create one or more partners. Each partner requires a name. Docs URL: https://docs.hoko.to/partners/post Markdown: https://docs.hoko.to/partners/post/README.md ## Endpoint POST /partners Create one or more partners. Accepts an array of partner objects. Each partner requires a name. Email and phone are optional. **Endpoint** ```text POST /partners ``` ## Authentication Requires an authorized credential with permission for `partnersWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body The request body must be an array of partner objects. Each object represents one partner to create. You can create up to 10,000 partners in a single request. Requests above 10,000 items are rejected. | Parameter | Type | Required | Location | Description | | --------- | -------------- | -------- | -------- | ----------------------------- | | name | string | Yes | body | The name of the partner. | | email | string (email) | No | body | Email address of the partner. | | phone | string | No | body | Phone number of the partner. | > **Warning: Request Size** > Ensure the request body contains at least one partner object. ## Status Codes ### 201 Partners created successfully. **Request** ```bash curl -X POST "https://api.hoko.to/partners" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "name": "Partner Name", "email": "partner@example.com", "phone": "+1234567890" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { name: 'Partner Name', email: 'partner@example.com', phone: '+1234567890' } ]) }); const partners = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Partner Name", "email": "partner@example.com", "phone": "+1234567890", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` ### 400 Invalid request body (missing required fields or invalid values). **Request** ```bash curl -X POST "https://api.hoko.to/partners" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ {} ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([{}]) }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X POST "https://api.hoko.to/partners" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'POST', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required partnersWrite scope. **Request** ```bash curl -X POST "https://api.hoko.to/partners" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'POST', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["partnersWrite"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X POST "https://api.hoko.to/partners" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'POST', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X POST "https://api.hoko.to/partners" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "name": "Partner Name", "email": "partner@example.com", "phone": "+1234567890" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { name: 'Partner Name', email: 'partner@example.com', phone: '+1234567890' } ]) }); const partners = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Partner Name", "email": "partner@example.com", "phone": "+1234567890", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` --- ### (PUT) Update/Upsert partners Update existing partners or create new ones with upsert operations. Docs URL: https://docs.hoko.to/partners/put Markdown: https://docs.hoko.to/partners/put/README.md ## Endpoint PUT /partners Upsert (update or insert) one or more partners. If id is provided, the partner is updated. If the ID does not exist, the request fails. To create new partners, omit the id field. **Endpoint** ```text PUT /partners ``` ## Authentication Requires an authorized credential with permission for `partnersWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body The request body must be an array of partner objects. Include the id field to update an existing partner, or omit it to create a new one. You can upsert up to 10,000 partners in a single request. Requests above 10,000 items are rejected. | Parameter | Type | Required | Location | Description | | --------- | ------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | id | string (ULID) | Yes | body | Required when updating. Omit to create a new partner. If provided, it must exist in your workspace or the request fails. | | name | string | No | body | The name of the partner. Required when creating a new partner (no id). Optional when updating. | | email | string (email)/null | No | body | Email address of the partner. If email or phone is null, the same payload must include a non-null email or phone value. | | phone | string/null | No | body | Phone number of the partner. If email or phone is null, the same payload must include a non-null email or phone value. | > **Info: Update Behavior** > When updating, include at least one mutable field besides id. Only the fields you include are changed. Omitted fields keep their current values. Null contact fields are accepted only when the same insert or update payload also provides at least one non-null contact value. > **Warning: Request Size** > Ensure the request body contains at least one partner object. ## Status Codes ### 200 Partners updated or created successfully. **Request** ```bash curl -X PUT "https://api.hoko.to/partners" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "id": "", "name": "Updated Partner", "email": "updated@example.com" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'PUT', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { id: '', name: 'Updated Partner', email: 'updated@example.com' } ]) }); const partners = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Updated Partner", "email": "updated@example.com", "phone": null, "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` ### 400 Invalid request body (missing required fields or invalid values). **Request** ```bash curl -X PUT "https://api.hoko.to/partners" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ {} ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'PUT', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([{}]) }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X PUT "https://api.hoko.to/partners" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'PUT', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required partnersWrite scope. **Request** ```bash curl -X PUT "https://api.hoko.to/partners" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'PUT', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["partnersWrite"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X PUT "https://api.hoko.to/partners" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'PUT', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X PUT "https://api.hoko.to/partners" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "id": "", "name": "Updated Partner", "email": "updated@example.com" } ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'PUT', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify([ { id: '', name: 'Updated Partner', email: 'updated@example.com' } ]) }); const partners = await response.json(); ``` **Response** ```json [ { "id": "", "name": "Updated Partner", "email": "updated@example.com", "phone": null, "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ] ``` --- ### (DELETE) Delete partners Delete one or more partners using soft delete. Docs URL: https://docs.hoko.to/partners/delete Markdown: https://docs.hoko.to/partners/delete/README.md ## Endpoint DELETE /partners Delete one or more partners (soft delete). Accepts an array of partner IDs to delete. **Endpoint** ```text DELETE /partners ``` ## Authentication Requires an authorized credential with permission for `partnersWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body The request body must be an array of partner IDs (ULIDs) to delete. You can delete up to 10,000 partners in a single request. Requests above 10,000 IDs are rejected. | Parameter | Type | Required | Location | Description | | --------- | ------------- | -------- | -------- | ------------------------------------------------------------------------------------------- | | body | array | Yes | body | Array of partner IDs (ULIDs) to delete. All IDs must be valid and belong to your workspace. | > **Warning: Request Size** > Ensure the request body contains at least one valid partner ID. ## Status Codes ### 200 Partners deleted successfully. **Request** ```bash curl -X DELETE "https://api.hoko.to/partners" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ "" ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'DELETE', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify(['']) }); const result = await response.json(); ``` **Response** ```json { "deletedIds": [""] } ``` ### 400 Invalid request body (missing IDs, invalid ULIDs, or IDs not found in your workspace). **Request** ```bash curl -X DELETE "https://api.hoko.to/partners" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ "invalid-id" ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'DELETE', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify(['invalid-id']) }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X DELETE "https://api.hoko.to/partners" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'DELETE', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required partnersWrite scope. **Request** ```bash curl -X DELETE "https://api.hoko.to/partners" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'DELETE', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["partnersWrite"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X DELETE "https://api.hoko.to/partners" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'DELETE', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` ## Examples **Request** ```bash curl -X DELETE "https://api.hoko.to/partners" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ "" ]' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/partners', { method: 'DELETE', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify(['']) }); const result = await response.json(); ``` **Response** ```json { "deletedIds": [""] } ``` --- ### Introduction Track lead and sale conversion events to connect marketing touchpoints to business outcomes. Automatically create and update customer records with flexible attribution tracking. Docs URL: https://docs.hoko.to/track/introduction Markdown: https://docs.hoko.to/track/introduction/README.md ## Overview Conversion tracking is the bridge between your marketing efforts and business outcomes. Track when leads convert and sales happen, connecting every click to revenue and business value. Hoko provides embedded click tracking for owned pages, plus two conversion tracking endpoints: Track Lead for capturing lead events (form submissions, sign-ups, inquiries) and Track Sale for recording completed purchases or revenue-generating actions. Lead and sale endpoints automatically create or update customer records, ensuring your customer database stays synchronized with your conversion tracking activities. When you track a conversion event, Hoko automatically associates it with the click that led to the conversion, providing complete attribution from initial click to final conversion. This enables you to measure campaign ROI, understand customer journeys, and optimize your marketing spend based on actual business results. - Embedded click tracking - Record a click from an owned page without redirecting the visitor - (POST) Track Lead - Record lead conversion events and automatically create/update customer records - (POST) Track Sale - Record sale conversion events with revenue attribution and customer upsert - Automatic customer creation/updates based on customerExternalId - Flexible attribution linking conversions to clicks, links, and partners - Support for immediate and deferred tracking scenarios > **Tip: Getting Started** > Enable conversion tracking on your links, then send lead or sale events when conversions occur. Use customerExternalId to maintain references to customers in your own system, ensuring seamless synchronization between Hoko and your CRM or other systems. --- ### Browser attribution script (analytics.js) Persist the clickId from short-link redirects using analytics.js and send it to conversion endpoints. Docs URL: https://docs.hoko.to/track/analytics-js Markdown: https://docs.hoko.to/track/analytics-js/README.md ## Overview The browser attribution script (`/analytics.js`) captures the `hoko_id` query parameter that Hoko appends to destination URLs and stores it as a cookie. This gives you a persistent clickId that you can send later when tracking leads or sales. > **Info: Outside the REST OpenAPI contract** > `/analytics.js` is a browser script endpoint, not an authenticated JSON REST endpoint. It is documented here for implementation guidance but is intentionally outside the OpenAPI REST contract. ## What it does - Reads `hoko_id` from the current page URL - Stores it in a cookie named `hoko_id` for 90 days - Replaces the existing `hoko_id` cookie when the current page URL contains a new `hoko_id` - Does not send any network requests > **Info: Lightweight by design** > The script only writes the cookie. It does not call any tracking endpoints automatically. ## Add the script Include the script on pages where users land after clicking a Hoko short link. ```html ``` ## Read the cookie and send events Read the `hoko_id` cookie and pass it as `clickId` to conversion tracking endpoints. ```javascript const clickId = document.cookie .split('; ') .find((row) => row.startsWith('hoko_id=')) ?.split('=')[1]; await fetch('https://api.hoko.to/track/lead', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify({ clickId: clickId ?? '', eventName: 'Sign up', customerExternalId: 'customer_123', customerName: 'John Doe' }) }); ``` ## When it runs The script runs when the browser loads it. It must execute on the same domain where you want the cookie to be stored. --- ### Embedded click tracking Track a Hoko short-link click from an owned page without redirecting the visitor. Docs URL: https://docs.hoko.to/track/embedded-click Markdown: https://docs.hoko.to/track/embedded-click/README.md ## Overview Embedded click tracking lets you record a normal Hoko click when a visitor lands on a page you control, without sending that visitor through the short-link redirect first. Use this when you already know which short link, referral code, partner code, or campaign should receive attribution on the page. > **Info: Outside the REST OpenAPI contract** > `/{shortId}/analytics.js` is a browser script endpoint, not an authenticated JSON REST endpoint. It is documented here for implementation guidance but is intentionally outside the OpenAPI REST contract. ## How it works - Create a dedicated Hoko short link, such as `https://hoko.to/1234` - Add the embedded analytics script using that short ID - Hoko verifies that the page requesting the script uses the short-link destination hostname or one of its subdomains - Hoko returns JavaScript with a short-lived signed capture token - The script reads or creates a first-party visitor session ID on the page, persists it for 90 days, then sends a signed capture request back to the same script URL - Hoko records the click only after that signed capture request is verified - The script first stores any `hoko_id` already present on the page URL - If the page URL does not include `hoko_id`, Hoko stores the generated embedded click ID as `hoko_id` - Conversion endpoints can later use `hoko_id` as the `clickId` > **Info: Redirect attribution wins first** > The embedded script includes the same page URL behavior as `/analytics.js`, so a `?hoko_id=...` from a normal short-link redirect takes priority. When there is no `hoko_id` on the page URL, the embedded click ID does not overwrite an existing `hoko_id` cookie. ## Add the script ```html ``` The short ID in the path identifies the Hoko link to track. Query parameters on the script URL are captured with the click. You do not need to include `https://hoko.to/analytics.js` alongside this script. The embedded script also persists `hoko_id` from normal short-link redirects. ## Host verification Embedded click tracking only records a click when both the browser `Origin`/`Referer` URL and the current page URL sent by the signed capture request use the short-link destination hostname or a genuine subdomain of it. For example, a short link that points to `https://example.com/pricing` can be embedded on `https://example.com/...`, `https://www.example.com/...`, `https://shop.example.com/...`, or a deeper subdomain. If the configured destination is `https://shop.example.com/...`, `https://checkout.shop.example.com/...` is allowed, but the parent `https://example.com/...` and sibling `https://blog.example.com/...` are not. An expired link with an expiry destination uses that destination hostname as its boundary. If the browser does not send a usable `Referer` or `Origin` header, either page URL falls outside the applicable destination boundary, or a URL is invalid, Hoko returns a no-op script and does not create a click. This protects clients from unrelated websites embedding their script and inflating their analytics. ## Supported attribution parameters | Parameter | Type | Required | Location | Description | | ------------ | ------ | -------- | -------- | --------------------------------------------------------------- | | shortId | string | Yes | path | The Hoko short ID in `/{shortId}/analytics.js`. | | utm_source | string | No | query | UTM source to store on the click. | | utm_medium | string | No | query | UTM medium to store on the click. | | utm_campaign | string | No | query | UTM campaign to store on the click. | | utm_term | string | No | query | UTM term to store on the click. | | utm_content | string | No | query | UTM content to store on the click. | | ref | string | No | query | Referral value to store on the click. | | referral | string | No | query | Alternative referral parameter. Used when `ref` is not present. | ## What gets captured The signed capture request is captured using the same short-link click pipeline as a redirect click. Hoko records request-level attributes such as timestamp, IP-derived location, visitor session ID, user agent, browser, operating system, device, language, browser referrer, and the UTM/referral parameters in the script URL. For embedded clicks, Hoko stores the browser's full current page URL as the click destination. Before recording the click, the server validates that this URL uses the applicable destination hostname or one of its subdomains. ## Conversion attribution After the script runs, read the `hoko_id` cookie and pass it to conversion endpoints. ```javascript const clickId = document.cookie .split('; ') .find((row) => row.startsWith('hoko_id=')) ?.split('=')[1]; await fetch('https://api.hoko.to/track/lead', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify({ clickId: clickId ?? '', eventName: 'Sign up', customerExternalId: 'customer_123', customerName: 'John Doe' }) }); ``` ## Behavior notes - The response is not cached, because each script request creates a short-lived capture token. - The script does not redirect the visitor. - A `hoko_id` on the current page URL is stored the same way as `/analytics.js`, including replacing an older cookie value. - Without a page URL `hoko_id`, the embedded click ID does not overwrite an existing `hoko_id` cookie. - The script does not mark clicks as QR scans. Use the normal short-link redirect for QR tracking. - If JavaScript is blocked, the embedded click is not recorded and the `hoko_id` cookie is not stored. - Browser referrer policies may limit how much of the page URL Hoko receives. The embedded script stores `document.referrer` as the click referrer, and still needs either a `Referer` or `Origin` header for host verification. - Pass page-specific attribution in the script query string when needed. --- ### Track lead events Docs URL: https://docs.hoko.to/track/lead Markdown: https://docs.hoko.to/track/lead/README.md ## Endpoint POST /track/lead Track a lead conversion event for a short link. This endpoint creates a lead event and upserts a customer record. **Endpoint** ```text POST /track/lead ``` ## Authentication Requires an authorized credential with permission for `conversionsWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body Accepts a single object (not an array). All fields are required unless marked optional. | Parameter | Type | Required | Location | Description | | ------------------ | -------------- | -------- | -------- | -------------------------------------------------------------------------------------- | | clickId | string | Yes | body | Click ID string to attribute the lead. Use an empty string ("") for deferred tracking. | | eventName | string | Yes | body | Lead event name (1-255 characters). | | customerExternalId | string | Yes | body | Customer external ID (1-100 characters). Used to upsert the customer. | | customerName | string | Yes | body | Customer name (max 100 characters). | | customerEmail | string (email) | No | body | Customer email, max 100 characters. Optional. Can be null to clear. | | customerAvatar | string (URL) | No | body | HTTPS customer avatar URL. Optional. Can be null to clear. | | metadata | object | No | body | Optional metadata object stored with the lead event. | > **Info: Deferred Tracking** > Send clickId as an empty string ("") to attribute the lead to the customer's most recent lead click. This fails if the customer has no previous leads. > **Info: Retries create lead events** > Every accepted POST creates a new lead event, including a retry. This includes caller retries. Repeated requests with the same customerExternalId reuse the active customer but create separate leads. No **Idempotency-Key** header is accepted, promised, or required. Retry only when another lead conversion is intended. > **Tip: Capture clickId in the browser** > If you don't already have a clickId, use the Browser attribution script to persist `hoko_id` and pass it to this endpoint. See [Browser attribution script](https://docs.hoko.to/track/analytics-js). ## Status Codes ### 201 Lead event tracked successfully. **Request** ```bash curl -X POST "https://api.hoko.to/track/lead" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "clickId": "", "eventName": "Sign up", "customerExternalId": "customer_123", "customerName": "John Doe", "customerEmail": "john@example.com" }' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/track/lead', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify({ clickId: '', eventName: 'Sign up', customerExternalId: 'customer_123', customerName: 'John Doe', customerEmail: 'john@example.com' }) }); const result = await response.json(); ``` **Response** ```json { "click": { "id": "" }, "link": { "id": "", "url": "https://example.com", "shortUrl": "https://hoko.to/abc123", "qrCode": "https://hoko.to/qrcode?text=https%3A%2F%2Fhoko.to%2Fabc123%3Fqr%3D1&size=512&errorCorrection=H&foreground=000000&background=FFFFFF&margin=1&format=svg", "title": null, "description": null, "image": null, "utm": null, "expiresAt": null, "expiredUrl": null, "password": null, "cloaked": false, "ios": null, "android": null, "geo": null, "collectionId": "", "tagIds": [""], "externalId": "ext_789", "tenantId": "tenant_456", "partnerId": "", "createdAt": "2024-01-01T00:00:00Z" }, "lead": { "id": "", "eventName": "Sign up", "metadata": { "source": "website" } }, "customer": { "id": "", "name": "John Doe", "email": "john@example.com", "phone": null, "avatar": "https://example.com/avatar.jpg", "externalId": "customer_123" } } ``` ### 400 Invalid request body, missing required fields, unknown clickId, or failed deferred tracking. **Request** ```bash curl -X POST "https://api.hoko.to/track/lead" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "clickId": "invalid-click-id", "eventName": "Sign up", "customerExternalId": "customer_123", "customerName": "John Doe" }' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/track/lead', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify({ clickId: 'invalid-click-id', eventName: 'Sign up', customerExternalId: 'customer_123', customerName: 'John Doe' }) }); ``` **Response** ```json { "error": { "en": "Click ID invalid-click-id not found or does not belong to your workspace", "ar": "معرف النقرة invalid-click-id غير موجود أو لا ينتمي إلى مساحة العمل الخاصة بك" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X POST "https://api.hoko.to/track/lead" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/track/lead', { method: 'POST', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required conversionsWrite scope. **Request** ```bash curl -X POST "https://api.hoko.to/track/lead" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/track/lead', { method: 'POST', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["conversionsWrite"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X POST "https://api.hoko.to/track/lead" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/track/lead', { method: 'POST', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` --- ### Track sale events Docs URL: https://docs.hoko.to/track/sale Markdown: https://docs.hoko.to/track/sale/README.md ## Endpoint POST /track/sale Track a sale conversion event for a short link. This endpoint creates a sale event and upserts a customer record. Every accepted POST creates a new sale, including a retry. This includes caller retries. Retrying the same request reuses the active customer but intentionally records another sale. No **Idempotency-Key** header is accepted, promised, or required. Retry only when another sale conversion is intended. **Endpoint** ```text POST /track/sale ``` ## Authentication Requires an authorized credential with permission for `conversionsWrite`. API keys are one supported credential; eligible OAuth or authenticated sessions may also authorize this operation. ## Request Body Accepts a single object (not an array). All fields are required unless marked optional. | Parameter | Type | Required | Location | Description | | ------------------ | -------------- | -------- | -------- | --------------------------------------------------------------------- | | customerExternalId | string | Yes | body | Customer external ID (1-100 characters). Used to upsert the customer. | | amount | integer | Yes | body | Sale amount (non-negative integer). | | currency | string | No | body | Currency code. Defaults to "usd". | | eventName | string | No | body | Sale event name. Defaults to "Purchase" (max 255 characters). | | metadata | object | No | body | Optional metadata object stored with the sale event. | | leadEventName | string | No | body | Lead event name to attribute this sale to a specific lead. | | clickId | string | No | body | Click ID string for direct sale attribution. | | customerName | string | Yes | body | Customer name (max 100 characters). | | customerEmail | string (email) | No | body | Customer email, max 100 characters. Optional. Can be null to clear. | | customerAvatar | string (URL) | No | body | HTTPS customer avatar URL. Optional. Can be null to clear. | > **Tip: Capture clickId in the browser** > If you want to attribute a sale directly to a click, use the Browser attribution script to persist `hoko_id` and pass it as clickId. See [Browser attribution script](https://docs.hoko.to/track/analytics-js). > **Info: Attribution Priority** > The sale is attributed in this order: leadEventName (if provided) → clickId (if provided) → most recent lead for the customer. If no lead exists and no clickId is provided, the request fails. ## Status Codes ### 201 Sale event tracked successfully. **Request** ```bash curl -X POST "https://api.hoko.to/track/sale" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "customerExternalId": "customer_123", "amount": 12900, "currency": "usd", "eventName": "Invoice paid", "customerName": "John Doe", "customerEmail": "john@example.com" }' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/track/sale', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify({ customerExternalId: 'customer_123', amount: 12900, currency: 'usd', eventName: 'Invoice paid', customerName: 'John Doe', customerEmail: 'john@example.com' }) }); const result = await response.json(); ``` **Response** ```json { "click": { "id": "" }, "link": { "id": "", "url": "https://example.com", "shortUrl": "https://hoko.to/abc123", "qrCode": "https://hoko.to/qrcode?text=https%3A%2F%2Fhoko.to%2Fabc123%3Fqr%3D1&size=512&errorCorrection=H&foreground=000000&background=FFFFFF&margin=1&format=svg", "title": null, "description": null, "image": null, "utm": null, "expiresAt": null, "expiredUrl": null, "password": null, "cloaked": false, "ios": null, "android": null, "geo": null, "collectionId": "", "tagIds": [""], "externalId": "ext_789", "tenantId": "tenant_456", "partnerId": "", "createdAt": "2024-01-01T00:00:00Z" }, "customer": { "id": "", "name": "John Doe", "email": "john@example.com", "phone": null, "avatar": null, "externalId": "customer_123" }, "sale": { "id": "", "amount": 12900, "currency": "usd", "eventName": "Invoice paid", "metadata": { "invoiceId": "inv_123" } } } ``` ### 400 Invalid request body, negative amount, or missing attribution data. **Request** ```bash curl -X POST "https://api.hoko.to/track/sale" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "customerExternalId": "customer_123", "amount": -100, "customerName": "John Doe" }' ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/track/sale', { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify({ customerExternalId: 'customer_123', amount: -100, customerName: 'John Doe' }) }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X POST "https://api.hoko.to/track/sale" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/track/sale', { method: 'POST', headers: { Authorization: 'Bearer invalid_key' } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required conversionsWrite scope. **Request** ```bash curl -X POST "https://api.hoko.to/track/sale" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/track/sale', { method: 'POST', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["conversionsWrite"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-\* headers for details. **Request** ```bash curl -X POST "https://api.hoko.to/track/sale" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch('https://api.hoko.to/track/sale', { method: 'POST', headers: { Authorization: 'Bearer ' } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ### 500 Unexpected server error. **Response** ```json { "error": { "en": "Internal server error", "ar": "خطأ داخلي في الخادم" } } ``` --- ### Introduction Receive signed workspace events securely in your backend, with a complete event catalog and delivery contract. Docs URL: https://docs.hoko.to/webhooks/introduction Markdown: https://docs.hoko.to/webhooks/introduction/README.md ## What this page covers Webhooks are signed server-to-server notifications from Hoko. When a subscribed workspace action is committed, Hoko sends a best-effort HTTPS POST to each eligible webhook. Use webhooks to synchronize your system or start work in your backend; use [Logs](https://docs.hoko.to/logs/introduction) to inspect the workspace activity fact that caused the message. The two concepts are related but not interchangeable: - A **log** is Hoko's small, immutable activity fact: what happened, which record it affected, who performed it, and when. - A **webhook delivery** is one outbound attempt to one receiver. It may be absent, pending, **Unconfirmed**, succeeded, or failed without changing whether the original activity was committed. `Unconfirmed` is the dashboard label for the persisted `unknown` state. - A **payload** is the same thin message contract for every subscribed event, including `lead.created` and `sale.created`. The [Webhooks help guide](https://help.hoko.to/webhooks) covers the dashboard flow. This page is the technical reference for access, every selectable event, signatures, payloads, receiver behavior, and limits. ### Identifiers Public webhook payloads use bare 26-character ULIDs. Examples use typed placeholders such as `` and ``; actual payloads contain the corresponding public IDs. Storage identifiers are not part of the public contract. ## Access and plan limits Manage webhooks in Dashboard → Integrations → Webhooks when webhooks are enabled in the deployment. Access requires an active account with owner membership in every active collection of the workspace, with at least one active collection. Blocked or deleted memberships do not qualify. Webhooks are workspace-wide; choosing a collection does not scope a webhook to that collection. Use the dashboard for interactive management. Programmatic actions are available only where the operation registry and the key's workspace scopes allow them; this reference defines the signed delivery contract. | Plan | Active webhooks | Log history shown | Webhook delivery | | ---------- | --------------: | ----------------: | ---------------- | | Free | `0` | `7 days` | Not available | | Pro | `0` | `30 days` | Not available | | Business | `10` | `90 days` | Available | | Enterprise | `20` | `180 days` | Available | | Elite | `40` | `365 days` | Available | Business, Enterprise, and Elite allow five additional storage slots for pending and disabled replacement webhooks, so the total stored configurations are 15, 25, and 45. A downgrade preserves excess configurations but suspends delivery to webhooks above the new active allowance. An upgrade makes eligible active webhooks available again; missed activity is not replayed. The active webhook ceilings are Business 10, Enterprise 20, and Elite 40. ## Create and verify a webhook 1. Prepare a public HTTPS receiver. Localhost, private, link-local, loopback, ambiguous IP, and redirect destinations are rejected by SSRF controls. 2. In the dashboard, enter a name and receiver URL, choose one or more events from the catalog below, and decide how to set the signing secret. Paste an existing canonical `whsec_` secret, use the shuffle control to generate one, or leave the field blank for Hoko to generate one. 3. Create the webhook. It starts as `pending_verification`. Copy the signing secret immediately and store it in server-only secret storage; it cannot be reopened from the dashboard. 4. Implement signature verification and the exact `endpoint.verification` challenge response before selecting **Verify webhook**. 5. A successful verification changes the webhook to `active`. Only active, plan-eligible webhooks receive subscribed workspace events. 6. Send a test and inspect its delivery. A test is a real outbound request; handle `endpoint.test` without triggering customer-facing business effects. Owner actions are limited to 10 verification attempts per hour and 30 combined test-send and resend actions per hour. Rate-limited actions return `429` with `Retry-After`. ## Event catalog The shared event catalog lists every workspace event available to Webhooks and Logs. Use it to understand each scope and action, then copy the exact event name from the table. [Browse the event catalog](https://docs.hoko.to/webhooks/event-catalog) ## Payloads Every selectable workspace event follows one payload contract: the same four-field JSON shape and JSON Schema version, 1.0. The version is in the published schema URL, not in the message body. `lead.created` and `sale.created` use this same contract; they do not include conversion details or record snapshots. ```json { "id": "", "type": "utmTemplate.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` | Field | Meaning | | ------------------ | ---------------------------------------------------------------------------------------------------- | | `id` | Stable event ID. It matches the `webhook-id` request header and is the receiver’s deduplication key. | | `type` | Exact event name from the [event catalog](https://docs.hoko.to/webhooks/event-catalog). | | `created` | Time the event was recorded, in ISO 8601 UTC format. | | `data.id` | Public ID of the affected record. | | `data.workspaceId` | Public ID of the workspace that owns the event. | Every selectable event schema has the same required fields and no additional payload fields. Use the scope page for an event’s affected record and example. Fetch more information from the relevant API when available. Schema documents are published at `/schemas/webhooks//1.0.json`. ### Webhook test and verification messages `endpoint.test` uses the same top-level fields and `data` contains only the webhook `id` and `workspaceId`. `endpoint.verification` also uses the same top-level fields, with `challenge` and `expiresAt` added to `data` because the receiver must echo the challenge before the webhook can be activated. These are operational messages, not selectable workspace events. ```json { "id": "", "type": "endpoint.verification", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "", "challenge": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8", "expiresAt": "2026-09-23T10:35:00.000Z" } } ``` ## Verify requests Download the tested [Node standard-library receiver example](/examples/webhooks/node-receiver.mjs). It reads `HOKO_WEBHOOK_SECRET` server-side and does not depend on a third-party package. Each request includes `content-type: application/json` and: | Header | Meaning | | ------------------- | ------------------------------------------------ | | `webhook-id` | Stable event ID and durable deduplication key | | `webhook-timestamp` | Unix timestamp in seconds | | `webhook-signature` | `v1,` followed by a base64 HMAC-SHA256 signature | Your receiver must: 1. Read the exact raw request bytes before parsing JSON. 2. Reject bodies over 64 KiB and timestamps outside ±300 seconds. 3. Compute HMAC-SHA256 over `webhook-id + "." + webhook-timestamp + "." + exactRawBody` using the canonical 32-byte `whsec_` key. 4. Compare equal-length signatures with `timingSafeEqual`. 5. Parse JSON only after verification and require its `id` to equal `webhook-id`. 6. For `endpoint.verification`, return exactly `{"challenge":""}` as JSON. 7. Atomically record a durable unique receipt keyed by `webhook-id` while persisting or queueing your work. 8. Return `2xx` quickly. A duplicate ID must also return `2xx` without repeating its side effect. An in-memory `Set` is not production deduplication. Use a database unique constraint or another durable atomic store. Verification must happen before any receipt, persistence, queue, or business side effect. Never parse and reserialize a body before verifying it; whitespace changes invalidate the signature. ## Delivery contract and limits Hoko writes the log and delivery row in the same transaction as the originating mutation, then awaits one best-effort outbound attempt from the committed request. Receiver failure does not roll back an accepted Hoko mutation. A rolled-back mutation sends no webhook. Delivery is immediate and request-bound, not a durable background queue. Business-plus workspaces can use webhooks, subject to their webhook allowance. Hoko supports fan-out to up to 40 active webhooks and keeps at most 1,000 delivery candidates in request memory. Large bulk operations can leave additional rows `pending` when the three-second receiver budget expires. Hoko makes one automatic attempt for each delivery, with no automatic retries or ordering guarantee. Owners can send an eligible delivery again from the log row's **More options** menu. The Webhooks dashboard side sheet displays the receiver URL and the 10 most recent attempts for the selected webhook. **See all deliveries** opens the dedicated per-webhook delivery history page from either the row's **More options** menu or the side sheet. That page uses paginated loading and supports sorting and filtering, so older attempts are loaded only when requested. Delivery states have these fixed meanings: - `pending`: the delivery row exists, but no attempt has started. - **Unconfirmed** (`unknown`): Hoko claimed the attempt but saved no terminal result. Hoko cannot prove whether the receiver received it, so this state is never reported as success or failure. - `succeeded`: Hoko recorded a successful sender result, not proof of downstream business completion. - `failed`: Hoko recorded a failure category such as timeout, DNS, TLS, network, unsafe destination, invalid challenge, or non-2xx response. The recorded categories are `success`, `unsafe_destination`, `dns_failure`, `invalid_message`, `oversized_request`, `timeout`, `tls_failure`, `network_failure`, `non_2xx`, `invalid_challenge`, `response_too_large`, and `pinning_unavailable`. Only `success` maps to `succeeded`; every other recorded category maps to `failed`. An Unconfirmed attempt has no category because Hoko saved no final result. Requests are limited to 64 KiB and three seconds of receiver time. Database work adds time to the originating request. There is no monthly webhook quota or overage billing; attempts are separate from tracked clicks and conversion usage. Hoko keeps delivery history for the workspace lifetime, including after a webhook is deleted. ### Resend a delivery Open **Logs**, find the event, and choose **More options → Resend** on a `pending`, `Unconfirmed`, or `failed` delivery. A pending delivery reuses attempt `1`. An Unconfirmed delivery can be resent after a five-minute cooldown. A failed delivery creates the next attempt number. Hoko records every result alongside the original result. A successful delivery cannot be resent from the dashboard. The resend uses the original event ID and a new signature timestamp. A targeted webhook test resends its original `endpoint.test` body. A log-backed broadcast keeps its original event type and body. Receivers must treat `webhook-id` as a durable idempotency key because an earlier attempt may have reached the receiver before Hoko recorded its result. Resending requires an active, plan-eligible webhook. ## Lifecycle, replacement, and troubleshooting The webhook moves through `pending_verification`, `active`, `disabled`, or `deleted`. Disabling stops new fan-out and cannot recall an already-sent request. To change the receiver URL, first disable the webhook and save the new URL. It returns to `pending_verification` while Hoko keeps the webhook ID, delivery history, and signing secret. Verify the new destination to activate it. To change the webhook name, subscribed events, or signing secret, create and verify a replacement, switch traffic, then disable and delete the old webhook. If both are active, the receiver may see the same event through both. Select **Delete webhook** when you no longer need the configuration. Deletion hides the webhook from management, preserves its name and delivery history, and erases signing material. It does not remove ordinary workspace log facts. Deleted webhooks cannot deliver or be resent. For a missing event, check the webhook is active, the event is selected, the action happened in this workspace, the plan still allows the webhook, and the delivery result. Old activity is not sent retroactively. For a failed delivery, fix the receiver and use **More options → Resend**. For an Unconfirmed delivery, assume the receiver may have applied the event, use the durable event-ID receipt to avoid duplicate processing, and resend only if needed. ## Security and data boundaries During local development, expose the receiver through a public HTTPS tunnel. Do not disable signature verification to make a tunnel work. Keep `HOKO_WEBHOOK_SECRET` and every `whsec_` signing secret in server-only secret storage. Never put a signing secret in browser code, a client bundle, `localStorage`, analytics, client logs, or a public repository. Payloads intentionally exclude record snapshots, customer name, email, phone, avatar, conversion metadata, API keys, signing secrets, destination credentials, full response bodies, raw IP addresses, exact location, visitor or session identifiers, the full referrer, destination query strings, and other database-row fields. Treat the included identifiers as sensitive business data. Do not log raw bodies, signature headers, secrets, URL query values, or challenge values. The canonical JSON and JavaScript examples are locale-neutral. Additional-language examples are not currently published. --- ### Event catalog Browse every workspace event available to Webhooks and Logs, with its scope, action, and exact event name. Docs URL: https://docs.hoko.to/webhooks/event-catalog Markdown: https://docs.hoko.to/webhooks/event-catalog/README.md ## Overview This is the shared vocabulary for Webhooks and Logs. **Scope** identifies the record family, **Action** describes the change, and **Event name** is the exact value to select or compare in code. Every event uses the same thin payload contract; open its scope page for the expected record ID and payload example. Use the copy control on the Event name column to copy a value. Global `profile.*` activity is not part of this workspace catalog. [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) · [Logs introduction](https://docs.hoko.to/logs/introduction) | Scope | Action | Event name | | -------------- | --------------------- | ------------------------------------- | | Workspace | created | `workspace.created` | | Workspace | name updated | `workspace.name.updated` | | Workspace | slug updated | `workspace.slug.updated` | | Workspace | image updated | `workspace.image.updated` | | API key | created | `apiKey.created` | | API key | updated | `apiKey.updated` | | API key | revoked | `apiKey.revoked` | | Link | created | `link.created` | | Link | clicked | `link.clicked` | | Link | destination updated | `link.destination.updated` | | Link | collection changed | `link.collection.changed` | | Link | tags changed | `link.tags.changed` | | Link | partner changed | `link.partner.changed` | | Link | UTM updated | `link.utm.updated` | | Link | preview updated | `link.preview.updated` | | Link | access updated | `link.access.updated` | | Link | targeting updated | `link.targeting.updated` | | Link | expiry updated | `link.expiry.updated` | | Link | QR settings updated | `link.qr.updated` | | Link | notes updated | `link.notes.updated` | | Link | external ID updated | `link.externalId.updated` | | Link | tenant ID updated | `link.tenantId.updated` | | Link | deleted | `link.deleted` | | Tag | created | `tag.created` | | Tag | updated | `tag.updated` | | Tag | deleted | `tag.deleted` | | Partner | created | `partner.created` | | Partner | updated | `partner.updated` | | Partner | deleted | `partner.deleted` | | UTM template | created | `utmTemplate.created` | | UTM template | updated | `utmTemplate.updated` | | UTM template | deleted | `utmTemplate.deleted` | | Collection | created | `collection.created` | | Collection | renamed | `collection.renamed` | | Collection | description updated | `collection.description.updated` | | Collection | deleted | `collection.deleted` | | Collection | default set | `collection.default.set` | | Collection | default cleared | `collection.default.cleared` | | Member profile | created | `memberProfile.created` | | Member profile | access updated | `memberProfile.access.updated` | | Member profile | removed | `memberProfile.removed` | | Member profile | left | `memberProfile.left` | | Member profile | ownership transferred | `memberProfile.ownership.transferred` | | Invitation | created | `invitation.created` | | Invitation | reissued | `invitation.reissued` | | Invitation | resent | `invitation.resent` | | Invitation | revoked | `invitation.revoked` | | Invitation | accepted | `invitation.accepted` | | Invoice | email sent | `invoice.email.sent` | | Subscription | created | `subscription.created` | | Subscription | plan changed | `subscription.plan.changed` | | Subscription | cancelled | `subscription.cancelled` | | Subscription | renewed | `subscription.renewed` | | Webhook | created | `webhook.created` | | Webhook | verified | `webhook.verified` | | Webhook | disabled | `webhook.disabled` | | Webhook | deleted | `webhook.deleted` | | Webhook | test requested | `webhook.test.requested` | | Customer | created | `customer.created` | | Customer | updated | `customer.updated` | | Customer | deleted | `customer.deleted` | | Lead | created | `lead.created` | | Sale | created | `sale.created` | --- ### Workspace Workspace lifecycle events and their signed payload contract. Docs URL: https://docs.hoko.to/webhooks/workspace Markdown: https://docs.hoko.to/webhooks/workspace/README.md ## Scope overview This page lists every **Workspace** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | ------------- | ------------------------- | ---------------- | | Created | `workspace.created` | `` | | Name updated | `workspace.name.updated` | `` | | Slug updated | `workspace.slug.updated` | `` | | Image updated | `workspace.image.updated` | `` | ## Event payload Every selectable event uses the same JSON Schema 1.0 payload. Only `type` and `data.id` vary by event. The payload identifies the event and affected record; it does not include a record snapshot. Fetch more detail through the relevant API when available. ```json { "id": "", "type": "workspace.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | -------- | ------------------------------------------------------ | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### API key API key lifecycle events and their signed payload contract. Docs URL: https://docs.hoko.to/webhooks/api-key Markdown: https://docs.hoko.to/webhooks/api-key/README.md ## Scope overview This page lists every **API key** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | ------- | ---------------- | -------------- | | Created | `apiKey.created` | `` | | Updated | `apiKey.updated` | `` | | Revoked | `apiKey.revoked` | `` | ## Event payload Every selectable event uses the same JSON Schema 1.0 payload. Only `type` and `data.id` vary by event. The payload identifies the event and affected record; it does not include a record snapshot. Fetch more detail through the relevant API when available. ```json { "id": "", "type": "apiKey.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | -------- | ------------------------------------------------------ | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### Link Link lifecycle and configuration events with their signed payload contract. Docs URL: https://docs.hoko.to/webhooks/link Markdown: https://docs.hoko.to/webhooks/link/README.md ## Scope overview This page lists every **Link** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | ------------------- | -------------------------- | ----------- | | Created | `link.created` | `` | | Clicked | `link.clicked` | `` | | Destination updated | `link.destination.updated` | `` | | Collection changed | `link.collection.changed` | `` | | Tags changed | `link.tags.changed` | `` | | Partner changed | `link.partner.changed` | `` | | UTM updated | `link.utm.updated` | `` | | Preview updated | `link.preview.updated` | `` | | Access updated | `link.access.updated` | `` | | Targeting updated | `link.targeting.updated` | `` | | Expiry updated | `link.expiry.updated` | `` | | QR settings updated | `link.qr.updated` | `` | | Notes updated | `link.notes.updated` | `` | | External ID updated | `link.externalId.updated` | `` | | Tenant ID updated | `link.tenantId.updated` | `` | | Deleted | `link.deleted` | `` | ## Event payload Lifecycle events use the shared JSON Schema 1.0 payload. A measured `link.clicked` event also includes `data.linkId` and `data.consent`; its `data.id` is the click event identity. The payload does not include a record snapshot or raw visitor data. ```json { "id": "", "type": "link.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | ---------------- | --------------------------------------------------------- | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | | `data.linkId` | `string` | Public ID of the link for `link.clicked`. | | `data.consent` | `string or null` | Explicit measurement consent, or `null` when unavailable. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### Tag Tag lifecycle events and their signed payload contract. Docs URL: https://docs.hoko.to/webhooks/tag Markdown: https://docs.hoko.to/webhooks/tag/README.md ## Scope overview This page lists every **Tag** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | ------- | ------------- | ---------- | | Created | `tag.created` | `` | | Updated | `tag.updated` | `` | | Deleted | `tag.deleted` | `` | ## Event payload Every selectable event uses the same JSON Schema 1.0 payload. Only `type` and `data.id` vary by event. The payload identifies the event and affected record; it does not include a record snapshot. Fetch more detail through the relevant API when available. ```json { "id": "", "type": "tag.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | -------- | ------------------------------------------------------ | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### Partner Partner lifecycle events and their signed payload contract. Docs URL: https://docs.hoko.to/webhooks/partner Markdown: https://docs.hoko.to/webhooks/partner/README.md ## Scope overview This page lists every **Partner** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | ------- | ----------------- | -------------- | | Created | `partner.created` | `` | | Updated | `partner.updated` | `` | | Deleted | `partner.deleted` | `` | ## Event payload Every selectable event uses the same JSON Schema 1.0 payload. Only `type` and `data.id` vary by event. The payload identifies the event and affected record; it does not include a record snapshot. Fetch more detail through the relevant API when available. ```json { "id": "", "type": "partner.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | -------- | ------------------------------------------------------ | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### UTM template UTM template lifecycle events and their signed payload contract. Docs URL: https://docs.hoko.to/webhooks/utm-template Markdown: https://docs.hoko.to/webhooks/utm-template/README.md ## Scope overview This page lists every **UTM template** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | ------- | --------------------- | ------------------- | | Created | `utmTemplate.created` | `` | | Updated | `utmTemplate.updated` | `` | | Deleted | `utmTemplate.deleted` | `` | ## Event payload Every selectable event uses the same JSON Schema 1.0 payload. Only `type` and `data.id` vary by event. The payload identifies the event and affected record; it does not include a record snapshot. Fetch more detail through the relevant API when available. ```json { "id": "", "type": "utmTemplate.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | -------- | ------------------------------------------------------ | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### Collection Collection lifecycle and default-state events with their signed payload contract. Docs URL: https://docs.hoko.to/webhooks/collection Markdown: https://docs.hoko.to/webhooks/collection/README.md ## Scope overview This page lists every **Collection** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | ------------------- | -------------------------------- | ----------------- | | Created | `collection.created` | `` | | Renamed | `collection.renamed` | `` | | Description updated | `collection.description.updated` | `` | | Deleted | `collection.deleted` | `` | | Default set | `collection.default.set` | `` | | Default cleared | `collection.default.cleared` | `` | ## Event payload Every selectable event uses the same JSON Schema 1.0 payload. Only `type` and `data.id` vary by event. The payload identifies the event and affected record; it does not include a record snapshot. Fetch more detail through the relevant API when available. ```json { "id": "", "type": "collection.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | -------- | ------------------------------------------------------ | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### Member profile Member access and ownership events with their signed payload contract. Docs URL: https://docs.hoko.to/webhooks/member-profile Markdown: https://docs.hoko.to/webhooks/member-profile/README.md ## Scope overview This page lists every **Member profile** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | --------------------- | ------------------------------------- | --------------------- | | Created | `memberProfile.created` | `` | | Access updated | `memberProfile.access.updated` | `` | | Removed | `memberProfile.removed` | `` | | Left | `memberProfile.left` | `` | | Ownership transferred | `memberProfile.ownership.transferred` | `` | ## Event payload Every selectable event uses the same JSON Schema 1.0 payload. Only `type` and `data.id` vary by event. The payload identifies the event and affected record; it does not include a record snapshot. Fetch more detail through the relevant API when available. ```json { "id": "", "type": "memberProfile.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | -------- | ------------------------------------------------------ | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### Invitation Invitation lifecycle events and their signed payload contract. Docs URL: https://docs.hoko.to/webhooks/invitation Markdown: https://docs.hoko.to/webhooks/invitation/README.md ## Scope overview This page lists every **Invitation** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | -------- | --------------------- | ----------------- | | Created | `invitation.created` | `` | | Reissued | `invitation.reissued` | `` | | Resent | `invitation.resent` | `` | | Revoked | `invitation.revoked` | `` | | Accepted | `invitation.accepted` | `` | ## Event payload Every selectable event uses the same JSON Schema 1.0 payload. Only `type` and `data.id` vary by event. The payload identifies the event and affected record; it does not include a record snapshot. Fetch more detail through the relevant API when available. ```json { "id": "", "type": "invitation.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | -------- | ------------------------------------------------------ | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### Invoice Invoice notification events and their signed payload contract. Docs URL: https://docs.hoko.to/webhooks/invoice Markdown: https://docs.hoko.to/webhooks/invoice/README.md ## Scope overview This page lists every **Invoice** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | ---------- | -------------------- | -------------- | | Email sent | `invoice.email.sent` | `` | ## Event payload Every selectable event uses the same JSON Schema 1.0 payload. Only `type` and `data.id` vary by event. The payload identifies the event and affected record; it does not include a record snapshot. Fetch more detail through the relevant API when available. ```json { "id": "", "type": "invoice.email.sent", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | -------- | ------------------------------------------------------ | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### Subscription Subscription lifecycle events and their signed payload contract. Docs URL: https://docs.hoko.to/webhooks/subscription Markdown: https://docs.hoko.to/webhooks/subscription/README.md ## Scope overview This page lists every **Subscription** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | ------------ | --------------------------- | ------------------- | | Created | `subscription.created` | `` | | Plan changed | `subscription.plan.changed` | `` | | Cancelled | `subscription.cancelled` | `` | | Renewed | `subscription.renewed` | `` | ## Event payload Every selectable event uses the same JSON Schema 1.0 payload. Only `type` and `data.id` vary by event. The payload identifies the event and affected record; it does not include a record snapshot. Fetch more detail through the relevant API when available. ```json { "id": "", "type": "subscription.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | -------- | ------------------------------------------------------ | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### Webhook Webhook endpoint lifecycle events and their signed payload contract. Docs URL: https://docs.hoko.to/webhooks/webhook Markdown: https://docs.hoko.to/webhooks/webhook/README.md ## Scope overview This page lists every **Webhook** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | -------------- | ------------------------ | -------------- | | Created | `webhook.created` | `` | | Verified | `webhook.verified` | `` | | Disabled | `webhook.disabled` | `` | | Deleted | `webhook.deleted` | `` | | Test requested | `webhook.test.requested` | `` | ## Event payload Every selectable event uses the same JSON Schema 1.0 payload. Only `type` and `data.id` vary by event. The payload identifies the event and affected record; it does not include a record snapshot. Fetch more detail through the relevant API when available. ```json { "id": "", "type": "webhook.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | -------- | ------------------------------------------------------ | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### Customer Customer lifecycle events and their signed payload contract. Docs URL: https://docs.hoko.to/webhooks/customer Markdown: https://docs.hoko.to/webhooks/customer/README.md ## Scope overview This page lists every **Customer** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | ------- | ------------------ | --------------- | | Created | `customer.created` | `` | | Updated | `customer.updated` | `` | | Deleted | `customer.deleted` | `` | ## Event payload Every selectable event uses the same JSON Schema 1.0 payload. Only `type` and `data.id` vary by event. The payload identifies the event and affected record; it does not include a record snapshot. Fetch more detail through the relevant API when available. ```json { "id": "", "type": "customer.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | -------- | ------------------------------------------------------ | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### Lead Lead events use the same thin, signed webhook payload as every other scope. Docs URL: https://docs.hoko.to/webhooks/lead Markdown: https://docs.hoko.to/webhooks/lead/README.md ## Scope overview This page lists every **Lead** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | ------- | -------------- | ----------- | | Created | `lead.created` | `` | ## Event payload Every selectable event uses the same JSON Schema 1.0 payload. Only `type` and `data.id` vary by event. The payload identifies the event and affected record; it does not include a record snapshot. Fetch more detail through the relevant API when available. ```json { "id": "", "type": "lead.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | -------- | ------------------------------------------------------ | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### Sale Sale events use the same thin, signed webhook payload as every other scope. Docs URL: https://docs.hoko.to/webhooks/sale Markdown: https://docs.hoko.to/webhooks/sale/README.md ## Scope overview This page lists every **Sale** event available to workspace webhooks. Use the exact event name in your receiver; the same activity is also recorded in [Logs](https://docs.hoko.to/logs/introduction). Each row identifies the affected record. ## Event list | Action | Event name | Record ID | | ------- | -------------- | ----------- | | Created | `sale.created` | `` | ## Event payload Every selectable event uses the same JSON Schema 1.0 payload. Only `type` and `data.id` vary by event. The payload identifies the event and affected record; it does not include a record snapshot. Fetch more detail through the relevant API when available. ```json { "id": "", "type": "sale.created", "created": "2026-09-23T10:30:00.000Z", "data": { "id": "", "workspaceId": "" } } ``` ## Data fields | Field | Type | Meaning | | ------------------ | -------- | ------------------------------------------------------ | | `id` | `string` | Stable event ID; also sent in the `webhook-id` header. | | `type` | `string` | Exact event name from the catalog. | | `created` | `string` | Event time in ISO 8601 UTC format. | | `data.id` | `string` | Public ID of the affected record. | | `data.workspaceId` | `string` | Public ID of the workspace that owns the event. | ## Related docs - [Webhooks introduction](https://docs.hoko.to/webhooks/introduction) - [Event catalog](https://docs.hoko.to/webhooks/event-catalog) - [Logs](https://docs.hoko.to/logs/introduction) - [Node receiver example](/examples/webhooks/node-receiver.mjs) --- ### Introduction Read the workspace activity ledger, understand every action and scope, and connect facts to webhook delivery. Docs URL: https://docs.hoko.to/logs/introduction Markdown: https://docs.hoko.to/logs/introduction/README.md ## What logs are Logs are Hoko's workspace activity ledger. Each row is a compact fact: an action happened to a record, an actor caused it, and Hoko recorded it at a specific time. Logs are designed for audit, investigation, and connecting a business change to its optional webhook deliveries. Logs are not click analytics, request/access logs, a database backup, a before-and-after snapshot, or a copy of the changed record. They do not require a webhook. A committed action can appear in Logs without any delivery, and a receiver failure does not undo the logged action. Use [Webhooks](https://docs.hoko.to/webhooks/introduction) for outbound payloads and receiver verification. Use the [Logs help guide](https://help.hoko.to/logs) for the dashboard workflow. ### Identifiers Log exports use bare 26-character ULIDs. Examples use typed placeholders such as `` and ``; actual exports contain the corresponding public IDs. Storage identifiers are not part of the public contract, and the dashboard resolves records and actors into useful names wherever possible. ## Access, history, and scale Open Dashboard → Integrations → Logs when the feature is enabled in the deployment. The view requires an active account with owner membership in every active collection of the workspace, with at least one active collection. Blocked or deleted memberships do not qualify. Results are workspace-wide, not limited to the selected collection. The dashboard view and programmatic access follow the current operation registry and workspace scopes. See the relevant operation and scope definitions before choosing a client. | Plan | Activity history shown | Page size | Filtering | | ---------- | ---------------------: | --------: | ----------- | | Free | `7 days` | `50` rows | Server-side | | Pro | `30 days` | `50` rows | Server-side | | Business | `90 days` | `50` rows | Server-side | | Enterprise | `180 days` | `50` rows | Server-side | | Elite | `365 days` | `50` rows | Server-side | The history window is a viewable allowance, separate from analytics retention and webhook-delivery inspection. Downgrades hide older entries without deleting them; upgrades reveal additional history only if it is still retained. Recording supported activity continues regardless of the viewing allowance, and logs do not consume tracked-click or tracked-event quota. The API uses bounded cursor pagination rather than loading the full ledger. Results are newest first, with at most 50 facts per page. The older-results cursor is based on the last row's timestamp and ID, so loading another page does not require an offset scan or a total-count query. Filters are applied before the page is returned. ## Event catalog The event catalog is shared with Webhooks and is the source vocabulary for the Logs scope and action filters. [Browse the event catalog](https://docs.hoko.to/webhooks/event-catalog) ## Stored fields and presentation The persisted log fact contains exactly seven fields. The dashboard may resolve a link and actor for display, and may join retained webhook deliveries, but those enrichments do not change the log fact itself. | Field | Meaning | Dashboard presentation | | ------------- | --------------------------------------------------------------- | --------------------------------------------------------------------- | | `id` | Stable identity of the log fact | Used for selection, cursors, and exports | | `workspaceId` | Workspace boundary | Not shown as a repeated column | | `recordId` | Affected record ID, not a record snapshot | Resolved when Hoko has a known link; otherwise shown as an identifier | | `action` | Dotted scope/action value from the catalog | Presented as Action + Scope, with the raw value in detail | | `actorId` | Profile or API key that caused the action; null for system work | Resolved to name/avatar or API-key name when available | | `operationId` | Groups related facts from one operation, including bulk changes | Available in the detail view and export | | `occurredAt` | Time the fact occurred | Full timestamp by default; compact relative time on hover | There is no arbitrary payload column, raw form dump, password, signing secret, or before/after value. Logs cannot reconstruct or restore a deleted record. A failed transaction does not leave a successful-change log. ## Browse, filter, and inspect 1. Select the workspace you want to inspect, then open Integrations → Logs. 2. Start with the newest page. Use the resource filter to narrow by scope, then the action filter to choose one action within that scope. 3. Select a row to inspect its resolved record, actor, operation, and related webhook deliveries. 4. Use **Load older activity** to request the next cursor page. Use **Back to newest** when browsing older history. 5. Clear the filters when no matching activity appears. No results can mean the action was never recorded, falls outside the plan window, or is not available in this workspace view. The viewer presents the action in user language while preserving the exact dotted value in the detail sheet. For links, the record can resolve to its short ID and destination. For actors, Hoko resolves a profile name/avatar or an API-key name; a missing actor means the system performed the action. ## Webhook delivery relationship A log can exist without a delivery. When an eligible active subscription matches the action, Hoko associates a delivery row with the log. Every webhook event uses the same thin payload: event ID, type, creation time, affected record ID, and workspace ID. `lead.created` and `sale.created` do not carry extra conversion fields. See [Webhooks](https://docs.hoko.to/webhooks/introduction). | Delivery state | Meaning in Logs | What it does not mean | | --------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | `pending` | A delivery row exists, but no attempt has started | It is not a scheduled retry or guarantee of later delivery | | **Unconfirmed** (`unknown`) | An attempt was claimed without a recorded terminal result. The UI never treats it as success or failure. | Hoko cannot prove whether the receiver received it | | `succeeded` | Hoko recorded a successful sender result | The receiver completed its business work | | `failed` | Hoko recorded a failure category and bounded result details | The original workspace action failed | No delivery shown does not mean the action failed. There may have been no eligible subscription, publication may have been disabled, the action may not be deliverable, or the endpoint may have been deleted. For a `pending`, **Unconfirmed**, or `failed` delivery, choose **More options → Resend**. Pending reuses attempt `1`, Unconfirmed requires a five-minute cooldown, and failed creates the next attempt number. A successful delivery cannot be resent from the dashboard. ## Export, retention, and privacy With data export access (Business or above), select visible rows and choose **Download selected**. The button shows the number of selected rows. The JSON export is an array containing only those rows from the current page: ```json [ { "id": "", "occurredAt": "2026-08-25T10:11:12.000Z", "action": "link.created", "recordId": "", "actorId": "", "operationId": "" } ] ``` Downloads do not fetch hidden history, resolved display data, or delivery details. Treat IDs as sensitive business data. There are no edit, delete, or restore controls. Deleting an endpoint removes its delivery history, not ordinary log facts; deleting a workspace can remove its associated logs. Hoko keeps delivery history for the workspace lifetime unless its endpoint or workspace is deleted. ## Boundaries and troubleshooting Logs show facts actually recorded by enabled application flows. They are not a retroactive narrative of all existing records, a database backup, or a guarantee that every external or direct database change is captured. If access is denied, verify workspace-wide owner membership, the active collection requirement, and deployment availability; a plan upgrade does not bypass the owner or deployment checks. If a known action is missing, check the selected workspace, the action's history window, the active filters, and whether the originating mutation committed. If a webhook is missing while the log exists, troubleshoot the endpoint and its delivery state in [Webhooks](https://docs.hoko.to/webhooks/introduction); do not treat the absence of a delivery as evidence that the action failed. ---