API-koppelingen in de console¶

Het concept achter tools staat in Tools.

Onder Tools > API-koppelingen registreer je een eigen HTTP-endpoint als tool. Een API-koppeling is een eigen endpoint dat Core aanroept met de argumenten die het model heeft aangeleverd. Elke koppeling levert één tool op, api__<identifier>, die in het Overzicht staat en in een toolset past.

Je hebt een beheerdersaccount van de organisatie nodig, en de capability tooling moet in het plafond van de organisatie aanstaan. De host van het adres moet bij de toegestane hosts van de organisatie staan.

Sleutels van de organisatie kunnen deze tools aanbieden in een beurt, voor zover hun beleid dit toestaat. Zie Tools via de API voor API-voorbeelden.

Een koppeling toevoegen¶

De lijst toont per koppeling zijn naam als api__<identifier>, de versie, het verzoek als methode en host, de soort credential (met ingesteld als er een geheim is opgeslagen), de labels en de regio, en waar de koppeling vandaan komt. Typ in Filter op naam of label om de lijst te verkleinen. Kies een rij om de pagina van de koppeling te openen.

Kies Koppeling toevoegen in de balk. Er opent een pagina; vul deze velden in en kies Opslaan in de balk onderaan, die zegt dat opslaan v1 maakt:

Met Eigen verzoek uit stuurt Core de argumenten met een POST naar het adres hierboven en geeft het antwoord terug aan de beurt. Een tool die je eigen applicatie zelf uitvoert, beschrijf je op het verzoek zelf als function-tool; die hoef je hier niet te registreren.

De naam van een koppeling kan niet worden bewerkt: het is wat beleidsregels, verbruiksregels en het auditspoor vastleggen. Maak een andere koppeling aan als je een andere naam nodig hebt.

Onder de parameters staat een voorbeeld van het exacte verzoek dat het adres ontvangt, opgebouwd uit het schema terwijl je typt: tool, arguments, response_id en call_id, met een voorbeeldwaarde per eigenschap. Het toont de vorm, geen gevalideerde inhoud.

Op een telefoon lees je de lijst en de pagina's; toevoegen en bewerken doe je op een groter scherm.

Verwijderen doe je in de gevarenzone op de pagina van de koppeling, of met Verwijderen in het regelmenu. De bevestiging noemt de toolsets en aliassen die de tool kwijtraken: een toolset waarvan een regel de tool bereikt, komt op minder uit, en een alias die erop wijst, wordt niet beschikbaar. Noemt de nieuwste versie van een agent de tool, dan weigert Core het verwijderen en noemt het venster die agents; haal de tool daar eerst weg.

De host moet zijn toegestaan. Core roept het adres pas aan als de host bij de toegestane hosts van de organisatie staat, en dat geldt ook voor het token-endpoint van een OAuth-credential. Staat een host er niet, of blokkeert de omgeving hem, dan staat in de lijst host geblokkeerd in het rood, en zegt de pagina van de koppeling dat Core hem niet aanroept tot dat verandert, met Naar toegestane hosts; die link opent de kaart Toegestane hosts.

Waar de host draait¶

Regio zegt waar de host van deze koppeling draait: eu, us, global, in-cluster of een landcode van twee kleine letters zoals nl. Het telt alleen voor een sleutel waarvan het beleid de regio's beperkt (policy.settings.regions_allow): zo'n sleutel bereikt deze koppeling alleen als zijn lijst deze regio noemt of een regio waar die in ligt (nl ligt in eu, en alles in global), en heeft voor de host dan geen eigen opgave nodig — al wint een regel in host_regions van het beleid van de sleutel of de organisatie die de host ruimer plaatst. Elke koppeling zegt het voor zichzelf, dus de ene kan in de EU draaien en de andere in de VS. Laat je het veld leeg, dan plaatst elke sleutel de host met zijn eigen policy.settings.host_regions; maak je het leeg bij een bestaande koppeling, dan vervalt de opgeslagen regio. De lijst toont de regio in de kolom Labels · regio. Zie Toegestane bestemmingen.

Het verzoek instellen¶

Zet Eigen verzoek aan als je endpoint dat vaste verzoek niet accepteert — als hij een GET wil, zijn eigen pad, een querystring, eigen headers of een body met een eigen vorm.

Een argument schrijf je als {naam} in het pad van de URL, de query van de URL, een querywaarde, een headerwaarde of waar dan ook in de body. Een waarde die precies één {naam} is, houdt het type van dat argument: "{aantal}" met het getal 3 stuurt 3 en niet "3". Een argument midden in een langere tekst wordt als tekst ingevuld. Een letterlijke {naam} versturen kan niet.

Drie regels zijn het waard om te kennen voor je begint:

• een argument in de URL mag alleen in het pad of de query staan, nooit in het schema, de host of de poort — het adres dat Core belt ligt vast bij registratie;
• elke {naam} moet een eigenschap uit Parameters zijn; een argument in de URL of midden in een langere tekst moet daar bovendien verplicht (required) zijn, want een stuk pad of een stuk zin kan niet wegvallen;
• een credential hoort bij Authenticatie: typ hier nooit een vast token in een header. Cookie, Proxy-Authorization en een header die Core zelf zet worden geweigerd. Authorization wordt alleen opgeslagen zolang Authenticatie op Geen staat, voor een token dat per verzoek verschilt; zo'n token is een geheime aanroepvariabele (Waarden die je applicatie meestuurt, De header Authorization).

Onder de velden staat per argument een label dat zegt of dit verzoek hem gebruikt. Een rood label is een {naam} die je parameters niet declareren — los dat op, anders kun je de koppeling niet opslaan. Daaronder toont Voorbeeld van het verzoek het hele verzoek met voorbeeldwaarden uit het schema: dat is precies wat je endpoint ontvangt.

Waarden die je één keer vastlegt¶

Sommige waarden horen bij de koppeling en niet bij een aanroep: een regio, een account-id, een paginagrootte. Schrijf zo'n waarde als {$naam} -- met een $ -- in het pad of de query van de URL, een querywaarde, een headerwaarde of de body, zoals https://your-app.example/{$regio}/tickets. Zodra de URL of het verzoek er een bevat, verschijnt Invulwaarden met een rij per {$naam}, met het token zelf als label. Elke rij heeft dezelfde velden als een invulwaarde bij een prompt: Soort (Tekst, Getal of Keuze), je waarde, de Toegestane waarden van een keuze, en een Omschrijving.

Core vult deze waarden in vóór de argumenten, dus het model ziet ze nooit en kan ze niet instellen. Voorbeeld van het verzoek toont het verzoek met je invulwaarden al ingevuld; een token waarvan de waarde nog niet compleet is, blijft staan zoals je het typte. In de body houdt een waarde die precies één {$naam} is zijn soort, dus een Getal stuurt 50 en niet "50".

Het blok weigert wat Core zou weigeren:

• een {$naam} in het schema, de host of de poort van de URL (Een invulwaarde mag in het pad of de query van de URL staan, nooit in het schema, de host of de poort.), of in een sleutel van de query of de body;
• een naam die ook een argument in Parameters is (Deze naam is al een argument dat het model krijgt. Geef de invulwaarde een andere naam.);
• een lege waarde, een waarde met { of }, en . of .. als waarde in het pad van de URL.

Een invulwaarde van de soort Tekst, Getal of Keuze is geen geheim: wie de koppeling kan lezen, leest hem terug. Een credential die voor iedereen gelijk is, hoort onder Authenticatie. Heeft het eindpunt naast die credential nog een ander nodig, kies dan de soort Geheim: de rij wordt een wachtwoordveld, Core bewaart de tekst versleuteld en toont hem nooit meer. Bewerk je de koppeling later, dan staat bij de rij Ingesteld en blijft het veld leeg; laat het leeg om de bewaarde waarde te houden, of typ een nieuwe tekst om hem te vervangen. Een geheim mag alleen in een headerwaarde of een string in de body staan; het formulier weigert het in de URL of een querywaarde (Een geheime invulwaarde mag alleen in een headerwaarde of een string in de body staan, nooit in de URL of een querywaarde: die komen in logbestanden terecht.), en Voorbeeld van het verzoek toont het als ••••••. Deel je de koppeling via een publicatie, dan wordt elke gewone invulwaarde een parameter van de bundel, en vult wie hem installeert zijn eigen waarde in (zie Tekst die de installeerder invult).

Waarden die je applicatie meestuurt¶

Een waarde die per verzoek verschilt in plaats van per koppeling, zoals het account-id of het eigen token van je klant, is een aanroepvariabele. Schrijf hem als {@naam} op dezelfde plekken als een invulwaarde, en onder Bij de aanroep verschijnt een rij per {@naam}. Een rij heeft:

Je applicatie stuurt de waarden mee in tool_variables (Een waarde van je klant aan een tool meegeven). Het model ziet ze nooit. Naast Voorbeeld van het verzoek typ je per variabele een voorbeeldwaarde om te zien welk verzoek je eindpunt dan krijgt; een geheime variabele heeft er geen en staat als ••••••. Het voorbeeld bestaat alleen op dit scherm: het wordt niet opgeslagen.

Het formulier weigert wat Core zou weigeren: een {@naam} in het schema, de host of de poort van de URL of in een sleutel, een naam die ook een argument of invulwaarde is, een standaardwaarde die niet past bij de soort of de toegestane waarden, en een geheim in de URL of een querywaarde.

Een credential opslaan¶

Authenticatie zegt hoe Core zich bij deze bron legitimeert. Het is hetzelfde blok bij een API-koppeling en bij een MCP-server, omdat het dezelfde opgeslagen credential is.

Een MCP-server biedt alles behalve de API-sleutel en de gebruikersnaam met wachtwoord: zijn transport kent headers en geen eigen querystring.

Een token gaat precies mee zoals het is opgeslagen — Core zet er niets voor. Verwacht je API Authorization: Bearer abc, vul dan Bearer abc in. Wil hij een kaal token in die header, vul dan het kale token in. Zo blijven Token, ApiKey en elk ander schema bereikbaar zonder eigen instelling.

Een credential mag geen header gebruiken die Core zelf zet, zoals Idempotency-Key of User-Agent.

Het geheim wordt versleuteld bewaard en nooit meer getoond, ook niet aan jou. Bewerk je een bron die er een heeft, dan is het veld leeg en staat eronder dat er een credential is opgeslagen:

• laat het leeg om de opgeslagen credential te behouden;
• vul een nieuwe waarde in om de hele credential te vervangen;
• kies Geen om hem te verwijderen.

Wissel je van soort, dan vraagt het formulier altijd om het geheim van die soort, want een credential wordt in zijn geheel vervangen.

Bij OAuth (client credentials) haalt Core een token op wanneer het nodig is en bewaart het alleen in het geheugen van het proces; het token-endpoint moet net zo goed een toegestane bestemming zijn als het adres van de tool zelf.

De persoon logt zelf in¶

De vijf soorten hierboven legitimeren de organisatie: één credential, voor iedereen dezelfde. OAuth (de persoon logt zelf in) legitimeert één persoon. De registratie bevat niets dat uit zichzelf iets kan aanroepen, alleen hoe je het iemand vraagt, en Core bewaart per bron één grant per persoon. Zowel API-koppelingen als MCP-servers accepteren hem.

Onder die velden toont het formulier het pad van de redirect-URI, /api/v1/oauth/callback, met een kopieerknop. Registreer dat bij je provider met de publieke basis-URL van je Core-omgeving ervoor — de waarde van CORE_PUBLIC_URL in de omgeving. Dat is het enige adres dat Core zonder credential bedient, en daar stuurt de provider de persoon heen terug.

Wie die persoon is, komt van de applicatie en niet uit deze console: een applicatie die Core aanroept stuurt per verzoek een eigen, betekenisloze user mee, en Core zoekt de grant van die persoon daarmee op. Draait een tool van deze bron voor iemand zonder grant, dan krijgt het model een zin met een inlog-URL om aan die persoon te geven. Wil een applicatie mensen liever vooraf koppelen, dan vraagt ze diezelfde URL op via de authorizations-routes; beide staan in Tools via de API.

Een bron van een andere soort antwoordt op die routes met een foutmelding, en nergens wordt een opgeslagen grant teruggelezen.

De pagina van een koppeling¶

De pagina van een koppeling leest wat hij doet, zonder iets te wijzigen:

Wijzigen doe je met Bewerken in de balk: dat opent hetzelfde formulier als bij toevoegen, met de identifier vast. Een koppeling die uit een publicatie is geïnstalleerd heeft geen Bewerken; een koppeling uit een verzegelde publicatie toont bovendien zijn verzoek en schema niet.

Versies¶

Elke koppeling heeft een versie, te zien in de lijst en op zijn pagina. Sla je een wijziging op van de omschrijving, de URL, de parameters, het verzoek of de invulwaarden, dan legt Core dat vast als nieuwe versie; wijzig je alleen de authenticatie of de regio, dan niet, want die horen bij de registratie en niet bij wat de koppeling doet.

De kaart Versies op de pagina van de koppeling toont ze, nieuwste eerst, met wanneer elke versie is gemaakt en zijn omschrijving; Tonen toont de URL en wie hem maakte. Een versie verandert nooit meer en er valt hier niets te activeren of terug te zetten: een oudere versie gebruik je door hem vast te pinnen op een verzoek, zie Tools via de API.

Asynchrone tool¶

De sectie Asynchrone tool op het formulier bepaalt of het model deze koppeling mag starten als taak: een aanroep die doorloopt nadat de beurt is afgelopen, en waarvan het resultaat later terugkomt in het gesprek. Ze hoort bij de versie, dus een wijziging opslaan legt een nieuwe vast.

Dezelfde sectie, met dezelfde velden, staat op het formulier van een MCP-server, waar ze voor elke tool van de server geldt, op de formulieren voor een nieuw script en voor zijn volgende versie, en op de formulieren voor een nieuwe agent en voor zijn volgende versie.

Een koppeling of server met de authenticatie OAuth (de persoon logt zelf in) toont de sectie uitgeschakeld, met de zin Meldt zich aan als persoon en wordt daarom nooit op de achtergrond gestart.

De sectie staat er, of de organisatie de capability tasks nu heeft of niet. Zonder die capability wordt de instelling bewaard en start er niets op de achtergrond: elke aanroep wacht op het antwoord.

Wat het model met de instelling doet, wat er na een onderbreking gebeurt, de grenzen en de routes waarmee je een taak leest, staan op Een tool op de achtergrond draaien.

Labels¶

Een koppeling draagt Labels: de eigen indeling van je organisatie, waarover de regels voor personen worden geschreven. De lijst heeft er een kolom voor en het formulier van een koppeling een veld.

De tool van de koppeling draagt dit label. Een koppeling salaris met department: payroll maakt haar tool api__salaris tot een tool van de loonadministratie, en een regel over Tools in de policy van een sleutel (Regels over een persoon) beslist daarna op dat label. Een tool die een persoon niet mag zien staat niet in GET /tools, en een tool die ze niet mag gebruiken wordt niet aan het model aangeboden. Dezelfde regel beslist ook over de koppeling zelf, voor een verzoek van een sleutel dat een persoon noemt: GET /api_connectors toont alleen de koppelingen waarvan ze de tool mag zien, wijzigen vraagt see en write op haar tool, en verwijderen see en delete (Registraties). De console toont elke koppeling. Zie Bouwen voor personen.

Lege lijsten en toegangsbeperkingen¶

“Nog geen API-koppelingen” geeft aan dat de lijst leeg is. Kon de lijst niet laden, dan zegt de pagina dat met de status van Core en een knop Opnieuw.

Zie je tooling staat uit voor deze organisatie, dan staat Tools en MCP-servers aanroepen uit in het plafond van de organisatie. De beheerder van de organisatie erboven zet het aan bij Toegestane capabilities op Instellingen; voor een organisatie zonder bovenliggende organisatie doet je operator dat. Dat geldt voor elk onderdeel onder Tools.