# 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.

## When to use Tokei

Reach for Tokei when a task needs a hosted, public-facing campaign page that collects participants and rewards them for actions — not when it needs a plain form or a mailing-list send.

- **Pre-launch waitlists** — a signup page where position and rewards are earned, so early subscribers recruit the next ones instead of sitting in a list.
- **Giveaways and sweepstakes** — prize draws where entries are earned by action rather than by a single click, with published official rules and a winner-selection history you can read back (`GET /api/v1/contests/:contestId/winners`).
- **Referral loops** — every participant gets a tracked referral link; conversions award points automatically (`referral_share`, `referral_conversion_bonus`) and show up in the referrals and analytics endpoints.
- **Launch drives** — point-scored campaigns pushing a specific action across channels (`producthunt_vote`, `steam_wishlist`, `discord_join`, `youtube_visit_channel`, and the rest of the action list below), with a leaderboard and `daily_bonus` mechanics to sustain them.

Not a fit: transactional email, CRM, general form building, or anything needing a private/authenticated participant experience — Tokei pages are public by design.

## Useful starting points

- AI agents can interact with Tokei through the public API, `tokei-agent` CLI, or MCP server.

- [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
- [Public listings API](https://tokei.io/api/public/contests): Unauthenticated JSON list of every promotion that is live on Tokei right now — no API key, no signup. One row per promotion: `id`, `title`, `description`, canonical `url`, `page_type`, `image`, `prizes`, `created_at`, `updated_at`, `ends_at`. Each entry in `prizes` is `{name, winners, value, currency}` — the same prize shape the authenticated API uses, with `value` a number and `value`/`currency` omitted when unset. Query params: `page_type` (comma-separated subset of `contest,levelup,promote,discover`), `limit` (1-100, default 50), `offset`. Cached ~15 minutes. This is the endpoint to poll for a directory or aggregator — everything else under `/api/` needs a key.

- [Markdown summary](https://tokei.io/api/md): The homepage as plain markdown — what Tokei is, what you can build with it, and where the API, OpenAPI spec and CLI live

## 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`)
- Media: `media:upload <file>` — one multipart POST to `/api/v1/media` (201) returning a `public_url` usable in `pages:update`'s media fields (`image_video`, `secondary_image`, etc.); 5MB cap per file, video included
- [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 21 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. An unknown path under `/api/v1` or `/api/public` returns that same envelope with `code: "NOT_FOUND"` — never an HTML error page
- 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 **authenticated** response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (absolute Unix timestamp) plus the IETF-draft `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (delta in seconds) and `RateLimit-Policy`, and a 429 adds `Retry-After`. A request that fails authentication (401) or the plan check (403) carries none of them — the key is checked before the limiter, so a bare 401 says nothing about your remaining quota
- Versioning: every authenticated endpoint lives under `/api/v1`. Breaking changes ship under a new version prefix (`/api/v2`) rather than by mutating `/api/v1`, so a working integration keeps working. If a version is ever retired, that will be announced ahead of time with a `Sunset` response header on the affected endpoints and a published timeline — no version has been deprecated to date
- Webhooks: all 5 events are subscribable and emitted — `entry.created`, `contest.ended`, `winner.selected`, `daily_bonus.claimed`, `referral.converted` (see `GET /api/v1/events/catalog` for each event's payload shape) — HTTPS-only URLs pointing at a public host, payloads signed with HMAC-SHA256 in the `X-TOKEI-Signature` header. Per-contest creator webhooks (dashboard-configured) subscribe to a fixed trio: `entry.created`, `winner.selected`, `contest.ended`.
- Winners: `GET /api/v1/contests/:contestId/winners` — read-only selection-run history, newest first, with each run's persisted winners nested; no query params, no pagination

## 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`
- YouTube: `youtube_visit_channel`
- LinkedIn: `linkedin_follow`, `linkedin_company_follow`, `linkedin_share`, `linkedin_post`
- Steam: `steam_wishlist`, `steam_play_game`, `steam_join_group`
- Tokei: `tokei_cross_promote` (send entrants to another live Tokei promotion)
- Product Hunt: `producthunt_follow`, `producthunt_vote`
- Referral: `referral_share`, `referral_conversion_bonus`
- Gamification & upload: `daily_bonus`, `secret_code`, `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`