Een speler koppelen aan zijn Lingara-account

API-versie 2026-10-virile-dragon

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

Koppelt een van je spelers aan het Lingara-account dat je app net toegang heeft gegeven. Roep het aan met het gedelegeerde token dat je server voor dat account heeft ontvangen, nooit met het eigen token van je client. Vanaf dan handelen de tokens van de speler als het account, voor zover de toestemming het toelaat: vraag om events:read, anders hoor je na de koppeling niets meer over de speler. Afgeronde plannen gaan naar het account; een plan dat nog wordt geschreven blijft tot je opnieuw aanroept. Veilig te herhalen: een herhaling antwoordt existing en verplaatst wat eerder niet kon worden verplaatst. Koppelen kost je niets.

Bevoegdheden embed:play

Parameters

Lingara-Versionheaderstringoptioneel: De API-versie waaronder dit verzoek wordt beantwoord. Zonder deze krijgt een toegangstoken de versie waaraan zijn client is gekoppeld, en een verzoek zonder token de huidige versie. De versie die nog in ontwikkeling is, bereik je alleen door die hier te noemen. Een onbekende versie geeft 400 met code api_version_unknown. GET /v1/versions toont de versies.
player_refpathstringverplicht: De player_ref waarmee je de tokens van de speler hebt uitgegeven, procentgecodeerd: guild/42 wordt guild%2F42.

Antwoorden

200 De koppeling van de speler

statusLinkStatusverplicht
subjectstringverplicht: De lgr_sub_ van het account: wat de gebeurtenissen van deze speler vanaf nu dragen.
previous_subjectstringverplicht: De lgr_sub_ van de gast: wat de eerdere gebeurtenissen van de speler behouden. Stuur beide naar dezelfde player_ref.
linked_atstringverplicht: Wanneer de koppeling is gemaakt. Bij een antwoord existing het tijdstip van de eerste aanroep.
scopesarray of stringverplicht: Het meeste dat een token voor deze speler nu kan bevatten: wat het account heeft toegestaan, van de scopes die een spelerstoken kan dragen.
carriedobjectverplicht: Rijen die deze aanroep naar het account heeft verplaatst, per tabel. Alleen tabellen met een aantal verschijnen.
keptobjectverplicht: Rijen die deze aanroep bij de gast heeft gelaten, per tabel: een plan dat nog wordt geschreven, of een rij die het account al had. Roep opnieuw aan zodra lesson_plans hier een afgerond plan heeft.

Fouten

402application/json: De aanroep van een client met verbruiksafrekening is geweigerd voordat die iets heeft uitgegeven. spend_cap_reached: de client of zijn account heeft zijn maandelijkse uitgavenlimiet bereikt; verhoog de limiet op de pagina Integraties. metered_billing_inactive: verbruiksafrekening is niet actief voor dit account; stel die in of werk de betaalmethode bij op de pagina Integraties.
410application/json: De API-versie waaronder dit verzoek wordt beantwoord, is stopgezet. Stuur een ondersteunde versie mee in Lingara-Version, of koppel de client aan een andere versie.
4XXapplication/json: Het verzoek is geweigerd. code geeft de reden aan en error beschrijft die in woorden.
503application/json · text/plain: De dienst is tijdelijk niet beschikbaar; probeer het opnieuw na het aantal seconden in Retry-After. Tijdens onderhoud is de body platte tekst in plaats van de foutenvelop.
5XXapplication/json: Het verzoek is geweigerd. code geeft de reden aan en error beschrijft die in woorden.

codestringverplicht: Waarom het verzoek is geweigerd, als stabiele code om op te vertakken: bijvoorbeeld insufficient_scope (403), rate_limited (429) en, voor een client met verbruiksafrekening, spend_cap_reached (402) en metered_billing_inactive (402).
errorstringverplicht

Voorbeeld

curl -X PUT "https://api.getlingara.com/v1/embed/players/$PLAYER_REF/link" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

Liever een bibliotheek? Zie de sectie Bibliotheken.

Als een vertaling afwijkt van de Engelse referentie, is de Engelse referentie juist.