Docs / API and tokensMenu

API and tokens

Publish messages, Live Activities, metrics and approvals with an hk_ token. Endpoints, errors and rate limits.

The workspace URL receives webhooks. For everything else, use an API token. A token acts as you, so keep it out of public code.

Create a token

In the Hook app, open Settings → API tokens, or use the web app. Name it, and copy the hk_… secret; it is shown once. You can have 20 tokens, and revoking one stops it at once. A token cannot create other tokens.

Publish

Send the Hook-* headers or a JSON body to /api/publish, with the token as a Bearer header. Add a topic to the path.

terminal
curl https://gethook.app/api/publish/deploys \
  -H "Authorization: Bearer hk_…" \
  -H "Content-Type: application/vnd.hook.message+json" \
  -d '{ "title": "Deployed", "message": "api v1.8.0", "priority": 3 }'

The token is removed before the request is stored, so it never shows in your inbox.

Endpoints

All take Authorization: Bearer hk_…. The full machine-readable list is at/openapi.json.

MethodPathWhat it does
POST/api/publish[/:topic]Send a message. Same fields as Publishing messages.
DELETE/api/messages/:id/notificationRemove a delivered notification.
PUT · DELETE/api/live-activity/stream/:keyStart or update, or end, a Live Activity.
GET/api/live-activity/streamsList streams.
PUT · DELETE/api/metrics/:keySet or delete a widget metric.
GET/api/metricsList metrics.
POST/api/badgeSet the app icon badge.
POST/api/approvalsAsk for an approval.
GET/api/approvals/:id?wait=25Read an approval, waiting up to 50 seconds.
GET · POST/api/tokensList or create tokens. Not with a token.

Details: messages, Live Activities,metrics and badge, approvals.

Teams and channels

Invite up to 10 people to your workspace. Members get its notifications, Live Activities, widget metrics and approvals on their own iPhones; any member can answer an approval. Set it up in the app (Settings → Team), in the web app, or with the API:

  • GET /api/team members, open invite codes, channels, and the teams you joined.
  • POST /api/team/invites a code valid for 7 days. The other person sends POST /api/team/join with { "code": "…" }.
  • DELETE /api/team/members/:userId removes a member; DELETE /api/team/memberships/:workspaceId leaves a team.
  • PUT /api/team/channels/:topic with { "member_ids": ["…"] } sends that topic to only those members (you always get it); null means everyone.

Errors

Errors are JSON: { "ok": false, "error": "…" }.

  • 400 a field is invalid. invalid_message_format and invalid_content_state name the field.
  • 401 unauthorized the token is missing, wrong or revoked.
  • 409 workspace_missing create a workspace in the app first.
  • 409 no_device no iPhone can show a Live Activity yet.
  • 429 rate limited. Wait and retry.

Rate limits

  • 60 webhooks a minute per workspace, including /api/publish.
  • 120 Live Activity and metric calls a minute per user.

Something wrong on this page? Email office@swiftapps.us.