Link a player to their Lingara account

API version 2026-10-virile-dragon

put https://api.getlingara.com/v1/embed/players/{player_ref}/link

Links one of your players to the Lingara account that just granted your app access. Call it with the delegated token your server received for that account, never with your client's own token. From then on the player's tokens act as the account, as far as the grant allows: ask for events:read or you hear nothing about the player after the link. Settled plans move to the account; a plan still being written stays until you call again. Safe to repeat: a repeat answers existing and moves what could not move before. Linking costs you nothing.

Scopes embed:play

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.
player_refpathstringrequired: The player_ref you minted the player's tokens with, percent-encoded: guild/42 is guild%2F42.

Responses

200 The player's link

statusLinkStatusrequired
subjectstringrequired: The account's lgr_sub_: what this player's events carry from now on.
previous_subjectstringrequired: The guest's lgr_sub_: what the player's earlier events keep. Route both to the same player_ref.
linked_atstringrequired: When the link was made. On an existing answer, the first call's time.
scopesarray of stringrequired: The most a token for this player can now hold: what the account granted, of the scopes a player's token can carry.
carriedobjectrequired: Rows this call moved to the account, per table. Only tables with a count appear.
keptobjectrequired: Rows this call left with the guest, per table: a plan still being written, or a row the account already had. Call again once lesson_plans here has a plan that has finished.

Errors

402application/json: A metered client's call was refused before it spent anything. spend_cap_reached: the client or its account has reached its monthly spending limit; raise the limit on the Integrations page. metered_billing_inactive: usage billing is not active for this account; set it up, or update the payment method, on the Integrations page.
410application/json: The API version this request is answered under has been discontinued. Send a supported version in Lingara-Version, or re-pin the client.
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 -X PUT "https://api.getlingara.com/v1/embed/players/$PLAYER_REF/link" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

Prefer a library? See the Libraries section.