Custom API clients
Connect any HTTPS client to Hoko's unversioned REST API.
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:
curl --request GET 'https://api.hoko.to/links' \
--header 'X-API-Key: <HOKO_API_KEY>' \
--header 'Accept: application/json'Authorization: Bearer <HOKO_API_KEY> 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:
curl --request POST 'https://api.hoko.to/links' \
--header 'X-API-Key: <HOKO_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'X-Request-Id: custom-client-create-001' \
--data '[{"url":"https://example.com/campaign","collectionId":"<collection_id>"}]'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:
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_KEYin 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.