Getting started

From nothing to the first JSON in five minutes. An immit account, a key, a curl, an entry.

  1. Make an account and a key

    Sign in to immit, open the console and create a key. Name it after the thing that will hold it. The secret is shown once; the console keeps only its first twelve characters, so copy it into your secret store before you close the dialog.

  2. Call /v1/me

    Every request carries the key as a bearer token. The first call proves the key and shows you the account's balance and the rates.

    curl 'https://api.immit.co/v1/me' \
      -H "Authorization: Bearer $IMMIT_API_KEY"
    200 · application/json
    {
      "id": "24b7bea1-1914-476c-b02f-4ca81ae34b70",
      "name": "My app",
      "prefix": "ik_live_cP_i",
      "balance": {
        "paid": "0",
        "allowance": "2",
        "allowance_returns_on": "2026-12-01"
      },
      "rates": {
        "word": "0.0004",
        "character": "0.000004",
        "monthly_allowance": "2",
        "requests_per_minute": 300
      },
      "inserted_at": "2026-11-20T05:58:11.936713Z",
      "last_used_at": "2026-11-20T05:58:11.977808Z"
    }
    • x-ratelimit-limit: 300
    • x-ratelimit-remaining: 299
    • x-ratelimit-reset: 49
    • x-balance-remaining: 2
  3. Look a word up

    The headword is UTF-8, percent-encoded. A headword that differs only in case, another spelling of the same word or an inflected form (食べた, went) resolves to the entry, and the canonical headword comes back in the response.

    curl 'https://api.immit.co/v1/dictionary/jpn/entries/食べる' \
      -H "Authorization: Bearer $IMMIT_API_KEY"
    200 · abridged
    {
      "id": "9bebf0ab-36ee-4511-a271-f8d0a21efe31",
      "headword": "食べる",
      "lang": "jpn",
      "frequency_rank": 334,
      "pronunciations": [
        {
          "reading": "たべる",
          "accent": 2,
          "sounds": [
            {
              "mp3_url": "https://storage.immit.co/sounds/01M45PR236JEQ21RS26407FZ32.mp3",
              "voice": "Himari",
              // …
            }
          ],
          // …
        }
      ],
      "senses": [
        {
          "pos": "動詞",
          "definition": "食物を口に入れ、かんで飲み込む。",
          "translations": {
            "eng": {
              "qualifier": null,
              "glosses": [
                {
                  "text": "to eat",
                  "readings": []
                },
                {
                  "text": "to have (a meal)",
                  "readings": []
                }
              ]
            }
          },
          // … homograph, pos_translations, examples, ids
        },
        // … 1 more sense
      ],
      "inflections": [
        {
          "text": "食べます",
          "form": "現在形",
          "tone": "polite",
          "polarity": "positive",
          // …
        },
        // … 42 more rows
      ],
      // … spellings, relations, updated_at
    }
  4. A query matches a headword prefix, an inflected surface form and, for Japanese, a reading, so 食べました finds 食べる and たべ finds it too. A Japanese reading may be typed in romaji: taberu finds 食べる. The order is immit's own ranking, the same the apps use.

    curl 'https://api.immit.co/v1/dictionary/jpn/entries?query=たべ&limit=3' \
      -H "Authorization: Bearer $IMMIT_API_KEY"
    200 · abridged
    {
      "metadata": {
        "after": null,
        "limit": 3,
        "before": null
      },
      "entries": [
        {
          "id": "9bebf0ab-36ee-4511-a271-f8d0a21efe31",
          "headword": "食べる",
          "lang": "jpn",
          "frequency_rank": 334,
          // … the full entry
        },
        {
          "id": "9323df1f-0ad8-4b00-9e7c-275da917e3d4",
          "headword": "たべっ子どうぶつ",
          "lang": "jpn",
          "frequency_rank": 108237,
          // … the full entry
        },
        {
          "id": "c7c50b63-cd93-4a09-9c9e-b737df9cccec",
          "headword": "食べつわり",
          "lang": "jpn",
          "frequency_rank": 162541,
          // … the full entry
        }
      ],
      "suggestions": []
    }
  5. Read the headers

    Every response carries where you stand: the burst a minute, and the dollars left in the account's balance. Each entry an answer carries draws one word from it, so a search costs what it returns. Over the burst is a 429 with retry-after, an empty balance is a 402, and a refused request is not counted. Rate limits and the balance has the table.

What next