Quickstart

API version 2026-10-affable-towhee

Five steps from nothing to a streamed vocabulary list: create a client, put it in your shell, exchange it for an access token, make one call, and get a new token when it runs out.

1. Create a client

On the Integrations page of the Lingara web app, at app.getlingara.com/admin, under OAuth clients, create a client that can Generate vocabulary (the scope vocab:generate). Copy its client ID and its secret. The secret is shown only once.

2. Put it in your shell

Store the client ID and secret in the LINGARA_CLIENT_ID and LINGARA_CLIENT_SECRET environment variables, so no secret is ever written into a command.

export LINGARA_CLIENT_ID="<your client id>"
export LINGARA_CLIENT_SECRET="<your client secret>"

3. Get an access token

This command exchanges the client for an access token and keeps it in LINGARA_TOKEN, which every example in this reference reads. It needs jq and curl 7.76 or later. If the exchange fails, the command prints the error code (for example invalid_client: check the ID and secret) and leaves LINGARA_TOKEN empty, so the next call fails with 401 until an exchange succeeds. Without jq, run the exchange from the Authentication guide and copy access_token from the response by hand.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=vocab:generate" | jq -r '.access_token // error(.error)')"

4. Generate a vocabulary list

Run this command. -N turns off curl's buffering, so each event prints as it arrives.

curl -N -X POST "https://api.getlingara.com/v1/vocab/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"level":2,"source_lang":"en","target_lang":"zh","count":8}'

What you should see

A started event with the list's details, one item event per word, then done. Your words will differ from this example.

event: started
data: {"meta":{"level":2,"source_lang":"en","target_lang":"zh","framework":"HSK","count":2,"ai_generated":true}}

event: item
data: {"word":"你好","pronunciation":"nǐ hǎo","translation":"hello","example":{"sentence":"你好，我叫小明。","translation":"Hello, my name is Xiaoming."}}

event: item
data: {"word":"谢谢","pronunciation":"xiè xie","translation":"thank you"}

event: done
data: {}

5. When the hour is up

The call answers 401. Run step 3 again. If step 3 now fails, the client or its secret has changed on the Integrations page. A program follows the Authentication guide's rule: exchange again once per 401, and stop if the exchange fails.