API

Base URL https://api.harkly.app/v1. Authenticate with an API key from Settings → API keys as a bearer token; keys carry permission sets, so a key for a CI job can read posts and nothing else.

curl https://api.harkly.app/v1/posts?sort=votes&limit=5 \
  -H "Authorization: Bearer hk_live_…"

• Reference: every route, request and response is generated from the spec at api.harkly.app/docs; the JSON is at /openapi.json.
• Typed client: import { createHarklyApi } from "@harkly/js/api" gives you the same spec as TypeScript types over openapi-fetch.
• Pagination is cursor-based: pass cursor from the previous page's nextCursor until it is null.
• Idempotency: send Idempotency-Key on writes and a retry returns the first response instead of doing the work twice.
• Rate limits come back as x-ratelimit-limit, -remaining and -reset on every response; 429 carries retry-after.
• Webhooks: subscribe to any event from Settings → Webhooks; every delivery is signed with the endpoint's secret and can be replayed.

For the customer-facing side (/identify, /track, the portal's own routes) use the public key instead of a bearer token: x-harkly-public-key.