API-referentie¶

De referentie beschrijft elke aanroep die je met een API-sleutel kunt doen: het verzoek, het antwoord en de statussen die je terug kunt krijgen. Wat een beheerder in de console doet staat er niet in, want dat bereik je niet met een sleutel. Je vindt de referentie op twee plekken bij je installatie, met dezelfde inhoud in een andere vorm.

Lezen¶

ReDoc toont de hele API op één pagina: per route de parameters, het request-schema, elk antwoord en de velden daarin. Gebruik deze vorm om op te zoeken wat een route verwacht en wat je terugkrijgt. De voorbeelden zijn gericht aan het Core-adres waarmee je installatie deze gids publiceert.

Uitproberen¶

Swagger UI doet dezelfde routes, maar voert ze ook uit. De pagina roept het adres aan dat bij Servers staat, en dat vult je installatie zelf in: controleer of het het adres is waarvoor je sleutel is uitgegeven en pas het aan als dat niet zo is. Klik daarna op Authorize, plak de secret van je sleutel en kies Try it out bij een route. Het antwoord dat je ziet komt van je eigen installatie. Je sleutel werkt daar alleen omdat dit de eigen gidspagina van je installatie is: een sleutel die een andere webpagina stuurt, wordt geweigerd (Een token voor de browser).

Het contract zelf¶

/api/openapi.json is het OpenAPI-document waar beide pagina's op draaien. Gebruik het om een client te genereren voor je eigen taal.

Basis-URL¶

Elke route in deze referentie roep je aan op één adres: het adres van je installatie, gevolgd door /api/v1.

https://<jouw-installatie>/api/v1

<jouw-installatie> is de host waarvoor je API-sleutel is uitgegeven. De beheerder van je organisatie kan je vertellen welke dat is. Voor de ontwikkelomgeving van Artific is de basis-URL https://build.dev.artific.nl/api/v1.

Waar deze gids een route schrijft als GET /key, roep je de basis-URL aan met dat pad erachter:

curl -s "https://<jouw-installatie>/api/v1/key" -H "Authorization: Bearer ack_..."

GET /key geeft de organisatie, de capabilities en het beleid van je sleutel terug en verandert niets. Zo controleer je een adres en een sleutel in één aanroep. De andere voorbeelden in deze gids bewaren de basis-URL in CORE_URL en de secret in CORE_KEY, die je instelt in Je eerste aanroep.

Deze gids heeft bij elke installatie dezelfde tekst, dus op de pagina's staat de plaatshouder. De twee verkenners hierboven tonen wel het adres van je eigen installatie. Swagger UI toont het in het veld Servers, zonder /api/v1, omdat elk pad in de lijst daar al mee begint. ReDoc toont het als je de methode en het pad van een route openklapt, als het volledige adres van die route.

Eén client krijgt een korter adres. De client van Anthropic plakt er zelf /v1/messages achter, dus zijn base_url eindigt op /api; zie De Anthropic-SDK gebruiken.

De OpenAI-SDK gebruiken¶

POST /responses antwoordt met het Responses-object van OpenAI, dus de officiële openai-client bereikt Core ongewijzigd: zet base_url op de /api/v1 van je installatie en geef de secret van je sleutel mee als api_key, die de client als bearer-token verstuurt. Ook fouten komen terug in de envelop van OpenAI, dus openai.APIStatusError bevat de melding, de param met het veld en de code.

from openai import OpenAI

client = OpenAI(base_url="https://<jouw-installatie>/api/v1", api_key="ack_...")
response = client.responses.create(model="<jouw-model>", input="Hallo", store=True)
print(response.output_text, response.conversation.id)

Drie dingen zijn goed om te weten. conversation is de thread waarop de beurt is opgeslagen, en dat is hetzelfde id dat de thread-routes verwachten. Een tool die Core voor je uitvoert komt terug als een mcp_call-item — zo noemt de Responses-API een tool die de server namens jou aanriep; een function-tool die je zelf uitvoert komt terug als function_call, precies zoals bij OpenAI. En een veld van OpenAI waar Core niets mee doet, wordt op een van drie manieren behandeld. Een hint die niet verandert wat het antwoord betekent — service_tier, include, prompt_cache_key — wordt aangenomen en genegeerd. Een veld dat een modelleverancier kan aannemen — top_p, parallel_tool_calls, een afgedwongen tool — wordt doorgegeven, en bij naam geweigerd met 400 als het model dat je noemde het niet kan aannemen. Een veld dat Core niet kan waarmaken — truncation: "auto", een gehost tooltype zoals web_search — wordt bij naam geweigerd met 400, zodat een aanroep die slaagt nooit minder betekent dan je schreef. Een codeeragent aansluiten noemt de velden per klasse.

Een opgeslagen agent bereik je zonder extra veld in de body: geef agent:<naam> (of het agt_-id) mee als model, en client.models.list() noemt de agents die je sleutel mag gebruiken naast de modellen. Je instructions gaan voor die van de agent, en response.model is het model waarop de agent draaide.

response = client.responses.create(model="agent:triage", instructions="Wees kort.", input="Hoi")

De typen van de SDK kennen de uitbreidingen van Core op de body niet. Geef een tool van Core, tools=[{"type": "tool", "name": "..."}], mee als gewone lijst of via extra_body, en een veld zoals helper via extra_body: extra_body={"helper": "acme.summary"}.

Authenticatie¶

Elke route buiten de beheerroutes verwacht de secret van je API-sleutel als bearer-token:

Authorization: Bearer ack_...

Zie Je eerste aanroep voor een sleutel aanvragen en je eerste verzoek versturen.

De Anthropic-SDK gebruiken¶

Core beantwoordt de Messages-API van Anthropic op /api/v1/messages, dus de eigen client van Anthropic werkt zonder aanpassing. Wijs hem naar je installatie en geef de secret van je sleutel mee als api_key, zoals de voorbeelden van Anthropic zelf doen; auth_token werkt ook en stuurt dezelfde secret als bearer-token:

import anthropic

client = anthropic.Anthropic(base_url="https://<jouw-installatie>/api", api_key="ack_...")
message = client.messages.create(
    model="<een model dat je sleutel mag gebruiken>",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Vat de tickets van deze week samen."}],
)

Het antwoord is het message-object van Anthropic. Een veld dat Core niet kan waarmaken — mcp_servers, container, een vast thinking.budget_tokens en een paar andere — wordt met naam geweigerd in plaats van genegeerd, zodat een verzoek nooit stilletjes minder betekent dan je schreef. top_p, top_k, stop_sequences en een afgedwongen tool gaan door naar het model; kan het model dat je noemde er een niet aan, dan noemt de weigering dat veld. Een hint die niet verandert wat het antwoord betekent, zoals cache_control of de header anthropic-beta, wordt aangenomen en genegeerd (Een codeeragent aansluiten). Het id dat je terugkrijgt is een Core-response-id: dezelfde waarde werkt op GET /responses/{id} en op GET /artifacts?response_id=.