Quickstart

This page takes you from zero to a streamed answer. It uses curl. Every step works the same way from a mobile client.

Before you start

You need three things:

The base URL. Production is https://client-api.lala.ist.
A Lala Supabase project. The client signs in against this project.
A Supabase access token for a signed-in user. Read Authentication for how to get one.

The token is a normal Supabase access token. Lala does not issue its own tokens, and there is no API key.

1. Check that the service is up

curl https://client-api.lala.ist/health

The response is {"ok":true}. This endpoint needs no token.

2. Create the student

curl https://client-api.lala.ist/api/me \
  -H "Authorization: Bearer $LALA_TOKEN"

The first call for a new user creates the student row and copies the identity out of the token: the e-mail, the phone number, the name from the sign-up form, and the avatar of the provider. Call it once after every sign-in, before you show the chat screen.

{
  "id": "9f1c0f2e-1f4a-4c5b-9a2d-0e0f1a2b3c4d",
  "phone": null,
  "email": "ogrenci@example.com",
  "profile": {
    "firstName": "Zeynep",
    "lastName": "Kaya",
    "preferredName": null,
    "displayName": "Zeynep",
    "email": "ogrenci@example.com",
    "phone": null,
    "examType": null,
    "field": null,
    "grade": "",
    "targetRanking": null,
    "targetRankingNum": null,
    "dailyHours": null,
    "strongSubjects": [],
    "weakSubjects": [],
    "onboardingComplete": false,
    "createdAt": "2026-08-02T09:12:44.000Z",
    "imageUrl": null
  },
  "onboardingComplete": false
}

If onboardingComplete is false, show the onboarding screen. Read Profile and onboarding.

3. Write the profile

curl -X PATCH https://client-api.lala.ist/api/profile \
  -H "Authorization: Bearer $LALA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"examType":"YKS","field":"Sayısal","grade":"12","dailyHours":6}'

The response holds the full profile after the update. onboardingComplete becomes true when grade and examType are set, and, for YKS, field too.

4. Stream an answer

curl -N -X POST https://client-api.lala.ist/api/chat/send \
  -H "Authorization: Bearer $LALA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Bugün matematik çalışacağım, nereden başlayayım?"}'

The -N flag disables buffering, so you see each event when it arrives. The response is a text/event-stream:

event: chunk
data: {"text":"Tamam, "}

event: chunk
data: {"text":"türevden başlayalım.","index":0}

event: message_end
data: {"index":0,"text":"Tamam, türevden başlayalım."}

event: done
data: {"text":"Tamam, türevden başlayalım.","messages":[{"id":"...","role":"lala","turnIndex":0}],"reactions":[]}

Open a bubble on each message_start, and append the chunk events to the bubble named by index. Lala answers in one message most of the time, and in two or three short ones sometimes. Replace your bubbles with the messages array of the done event. Read Stream a chat answer for the full contract.

5. Read the history back

curl "https://client-api.lala.ist/api/chat/messages?limit=50" \
  -H "Authorization: Bearer $LALA_TOKEN"

The endpoint returns one page, oldest first. Send the nextCursor of the response as before to read older messages. Call it when the chat screen opens. Read Conversation history.

Start here

Build

Understand

For agents

Before you start

1. Check that the service is up

2. Create the student

3. Write the profile

4. Stream an answer

5. Read the history back

Next steps

Errors and limits

Push notifications

​Before you start

​1. Check that the service is up

​2. Create the student

​3. Write the profile

​4. Stream an answer

​5. Read the history back

​Next steps

Errors and limits

Push notifications

Before you start

1. Check that the service is up

2. Create the student

3. Write the profile

4. Stream an answer

5. Read the history back

Next steps