Automation recipes
Create Hoko links from customer-owned automation systems with durable mappings and safe reconciliation.
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 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:
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.tsThe 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.
Authorization: Bearer <HOKO_API_KEY>Use the unversioned resource routes. Do not add an API prefix or gateway prefix:
GET https://api.hoko.to/usage
GET https://api.hoko.to/links?externalId=<external_id>
POST https://api.hoko.to/links
GET https://api.hoko.to/links?id=<link_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 and the OpenAPI document.
Keep one mapping per external record
Store a durable intent before a non-idempotent create. Use this identity:
(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:
hoko:automation:<provider>:<encoded-account-identity>:<encoded-foreign-record-id>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
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 returned429; respectRetry-Afterand inspect the mapping before any later attempt.
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:
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.