# Tokei

> Tokei (tokei.io) is a contest, giveaway, and gamified promotion platform. Creators run competitions where participants earn points for actions (email signup, social follows, referrals, daily bonuses, surveys). The Tokei Public API lets you manage contests, create entries programmatically, pull analytics and leaderboards, and receive signed webhooks when participants enter.

## Docs

- [API Reference](https://tokei.io/docs/api): Full public API documentation — authentication, endpoints, errors, rate limits, webhooks
- [OpenAPI Spec](https://tokei.io/openapi.json): Machine-readable OpenAPI 3.0 description of every endpoint
- [Product Docs](https://tokei.io/docs): Platform documentation — contest setup, entry actions, email integrations, gamification

## Agent tooling

- [Agent landing page](https://tokei.io/agent): Overview of `tokei-agent` for AI agents — install/quickstart, worked workflows (build a page, read stats, wire a webhook), Claude Code + OpenClaw setup, and agent-safe key options
- CLI: [`tokei-agent` on npm](https://www.npmjs.com/package/tokei-agent) — zero-dependency CLI wrapping every v1 endpoint; all commands print JSON (`npx tokei-agent --help`)
- [SKILL.md](https://unpkg.com/tokei-agent/SKILL.md): Agent-facing skill reference bundled in the npm package — every command with a worked example, terminology mapping (API "contest"/"promotion" = UI "page"/"campaign"), error semantics, and rate-limit self-throttling
- MCP server: `npx tokei-agent mcp` — local stdio server exposing the same 17 operations as MCP tools; for Claude Code: `claude mcp add tokei --env TOKEI_API_KEY=<key> -- npx -y tokei-agent mcp`

## API key facts

- Base URL: https://tokei.io/api/v1
- Authentication: `Authorization: Bearer tokei_k_...` header (keys are generated in Dashboard > Settings > API; requires an active subscription or lifetime plan)
- Responses: JSON, `{ "success": true, "data": ... }` on success, `{ "success": false, "error": { "code", "message", "status" } }` on error
- Pagination: `page` and `per_page` query parameters (default 25, max 100), `pagination` object in list responses
- Rate limits: per account — Subscriber 60 read / 30 write per minute, Lifetime 120 read / 60 write per minute; every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
- Webhooks: `entry.created` is the only subscribable event (`contest.ended`, `winner.selected`, `daily_bonus.claimed` are reserved but not yet emitted — subscribing to them returns 422) — HTTPS-only URLs pointing at a public host, payloads signed with HMAC-SHA256 in the `X-TOKEI-Signature` header

## Action types

- `action_type` on an entry records how it was earned. It defaults to `api_import` and accepts any custom string matching `^[a-z0-9_-]+$` (no whitelist), so the list below is canonical but not exhaustive.
- Email & web: `email_signup`, `visit_website`
- Twitter/X: `twitter_follow`, `twitter_like`, `twitter_retweet`, `twitter_view_post`, `twitter_tweet`
- Instagram: `instagram_follow`, `instagram_view_post`, `instagram_share_photo`
- TikTok: `tiktok_follow`, `tiktok_watch`
- Facebook: `facebook_visit_page`, `facebook_view_post`, `facebook_join_group`
- Discord: `discord_join`
- Twitch: `twitch_follow`, `twitch_subscribe`
- LinkedIn: `linkedin_follow`, `linkedin_company_follow`, `linkedin_share`, `linkedin_post`
- Steam: `steam_wishlist`, `steam_play_game`, `steam_join_group`
- Product Hunt: `producthunt_follow`, `producthunt_vote`
- Referral: `referral_share`, `referral_conversion_bonus`
- Gamification & upload: `daily_bonus`, `user_upload`
- API: `api_import` (default for entries created via the API)
- Read-only (appear in analytics breakdowns but are not settable via the API): `oauth_login`, `social_share`, `survey`