Stream events

Parameters

Lingara-Versionheaderstringoptional

The API version to answer this request under. Without it, an access token gets the version its client is pinned to, and a request with no token gets the current version. The version still in development is reached only by naming it here. An unknown version answers 400 with code api_version_unknown. GET /v1/versions lists the versions.

Last-Event-IDheaderstringoptional

The id: of the last event you received. It takes precedence over cursor and start.

cursorquerystringoptional

Where to continue from: an earlier page's next_cursor, or a stream event's id:. A cursor older than 30 days answers 410 with code cursor_expired.

startquerystringoptional

Where to begin without a cursor: latest for events from now on, or oldest for every event still kept.

typesqueryarray of stringoptional

Only these event types, comma-separated. Without it, every type your token's scopes can read.

Responses

200 Events as they happen, until done or error

Stream events text/event-stream

Sends a keepalive comment every 15 seconds.

event EventEnvelope

idstringrequired

typestringrequired

created_atstringrequired

api_versionstringrequired

subjectstringrequired

dataobjectrequired

done Done Ends the stream

error StreamError Ends the stream

Arrives inside the 200 response. The status line has already been sent, so a failure after the stream opens is reported as this event.

codestringrequired

messagestringrequired

plan_idstring | nulloptional

Errors

410application/json

api_version_discontinued: this request's API version has been discontinued. cursor_expired: the cursor is older than 30 days; start again without one.

4XXapplication/json

The request was refused. code says why, and error says it in words.

503application/json · text/plain

The service is temporarily unavailable; retry after the number of seconds in Retry-After. During maintenance the body is plain text rather than the error envelope.

5XXapplication/json

The request was refused. code says why, and error says it in words.

codestringrequired

Why the request was refused, as a stable code to branch on: for example insufficient_scope (403), rate_limited (429) and, for a metered client, spend_cap_reached (402) and metered_billing_inactive (402).

errorstringrequired

Example

curl -N "https://api.getlingara.com/v1/events/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

Prefer a library? See the Libraries section.

Example stream

id: djEuNzQ0MTIuOTkxLjE3OTAyNDk1NjQ
event: event
data: {"id":"lgr_evt_4f2a9c1e7b3d4e5f8a9b0c1d2e3f4a5b","type":"lesson_plan.ready","created_at":"2026-10-01T09:12:44Z","api_version":"2026-09-equipped-boxfish","subject":"lgr_sub_0f1e2d3c4b5a69788796a5b4c3d2e1f0","data":{"plan_id":"3f1c2a9e-5b7d-4e21-9a0c-6d8e4f2b1a37","status":"complete","title":"At the night market","source_lang":"en","target_lang":"zh","level":2}}

id: djEuNzQ0MzAuMC4xNzkwMjUwNDY0
event: done
data: {}