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:

Code sh
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.

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:

ResponseMeaningClient action
400Malformed JSON or invalid operation inputFix the request. Do not retry unchanged.
401Missing, invalid, or revoked credentialReplace or revoke the credential in the client.
403The key lacks the required scope or workspace accessGrant the narrow required scope or choose an allowed resource.
404Missing resourceCheck the resource path or resource ID.
429The shared admission limit is exhaustedWait for Retry-After, then retry a safe request.
5xxHoko could not complete the requestRetry 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.