FeedbackGet API access
Developer

Build on the API & SDKs

7:50 walkthrough

The Toktik Developer API is a metered REST API, plus official SDKs — @toktikhq/sdk-js for JavaScript/TypeScript and toktik for Python. Start with the quickstart, auth and credits, then copy ready-made cURL, JavaScript and Python examples.

What you'll learn

  • Mint a key and make your first authenticated request
  • Understand scopes, rate limits and the credit model
  • Use the JavaScript and Python SDKs
  • Read the docs: quickstart, endpoints and scopes

How it works

  1. Create a key in Settings

    In the app open Settings, then Developer keys, and create a key with only the scopes you need, such as rank:read for rankings. The secret starts with ttk_live_ and is shown once, so store it in an environment variable. Keys can only reach data routes, and creating keys stays a signed-in action.

  2. Make your first request

    Send the key as Authorization: Bearer with your ttk_live_ secret. The docs quickstart calls the official rankings board at api.toktikhq.com/v1/rankings/official with board=hourly and region=VN. A 403 means the key lacks the scope for that route.

  3. Work within limits and credits

    Each key has a per-second request limit by plan, from 1 on Free to 150 on Agency. Over the limit you get 429, so wait for Retry-After and retry. Running out of credits returns 402, which retrying will not fix, and GET /v1/usage shows your spend.

  4. Add an official SDK

    Install npm i @toktikhq/sdk-js for JavaScript and TypeScript, or pip install toktik for Python; both call the same v1 REST API with the same key and the same credit wallet. The Docs pages Quickstart and API Reference list every endpoint, parameter and scope.

Frequently asked questions

How much does the Toktik API cost?

There is no separate API price list. The web app and the API spend the same credit wallet on the same plan. A read served from Toktik's store costs 1 credit, an export costs 2,500 credits, and on-demand collection calls cost more.

What are the Toktik API rate limits?

Per key, per second: Free 1, Starter 5, Pro 20, Scale 60 and Agency 150. Daily quotas also apply, from 5,000 requests on Free to 1,200,000 on Agency. Exceeding the limit returns 429 with headers showing the window state.

Does Toktik have official SDKs?

Yes. @toktikhq/sdk-js covers JavaScript and TypeScript, and the toktik package covers Python. Both call the same v1 REST API with the same key.

What is the difference between a 402 and a 403 from the Toktik API?

A 402 means the workspace is out of credits, so top up rather than retry. A 403 means the key is valid but lacks the required scope, so grant it or use a signed-in session. A 429 is a rate limit and is safe to retry after backing off.

Read the API docs All guides

More in this section