API-reference

komplais API tager imod JSON og svarer med JSON over HTTPS. Hvert kald sender din nøgle i headeren Authorization:

curl https://api.komplai.dk/v1/access \
  -H "Authorization: Bearer $KOMPLAI_TOKEN"

GET /v1/access viser, hvad din nøgle har adgang til, hvor hvert lag i Redact behandler tekst, og hvilke grænser der gælder. API-nøgler og autentificering forklarer de to slags nøgler.

Endpoints

Hvert endpoint viser de scopes og nøgler, det kræver, dets felter og dets svar, med kodeeksempler i curl, PowerShell, Python, JavaScript og C#. Eksemplerne læser din nøgle fra miljøvariablen KOMPLAI_TOKEN. Når du er logget ind i hubben, viser API og integrationer › API-reference de operationer, din egen adgang dækker.

Beskrivelserne af endpoints, felter og fejl er på engelsk, ligesom i API'ets eget OpenAPI-dokument.

Adresser

Opret nøglen i hubben i det miljø, du kalder. Hvert miljø udleverer OpenAPI-dokumentet for den version, det kører, på /v1/openapi.json.

Versioner og stabilitet

Alle stier begynder med /v1. info.version i OpenAPI-dokumentet er versionen af kontrakten, 1.3.0 i det dokument, referencen her er bygget af. Ændringsloggen viser, hvad hver version ændrede.

Hver operation har x-komplai-stability:

• stable beholder sin kontrakt.
• beta kan stadig ændre sig, og komplai varsler, før det sker. Decide, Coding og Redacts input fra PDF- og Word-filer er i beta.
• alpha er på et tidligt stadie og kan ændre sig uden varsel.

Et felt i et kald, der er mærket preview, er en tidlig mulighed i en operation og kan ændre sig uden varsel: Redacts engine og sources. Udelad dem, medmindre jeres administrator har slået forhåndsvisningen af Redact Agentic til.

OpenAPI-dokumentet

/openapi.json på dette site er OpenAPI 3.1, en kopi af det dokument, produktions-API'et udleverer på https://api.komplai.dk/v1/openapi.json. Referencen her er bygget af det. GET /v1/openapi.json kræver ingen nøgle og ignorerer headeren Authorization, så et værktøj, der altid sender en nøgle, stadig får dokumentet.

Ud over standard-OpenAPI har dokumentet:

Importér i Postman

• OpenAPI-dokumentet: OpenAPI 3.1.
• Postman-samlingen: alle endpoints med eksempler på body, delt op som i denne reference, med bearer-godkendelse fra variablen token.
• Postman-miljøet: variablerne baseUrl (https://api.komplai.dk) og token, en hemmelig variabel, der starter tom.

Valgfrie headere, fx Idempotency-Key og Prefer, står i de kald, der bruger dem, men er slået fra. Idempotency-Key indeholder Postmans {{$guid}}, et nyt UUID ved hver afsendelse. I andre værktøjer laver du et UUID til hvert job eller udelader headeren.

Kald og svar

• Send en body som JSON med Content-Type: application/json. En anden indholdstype svarer 400 eller 415.
• Redact, Chat og Coding afviser et felt, de ikke dokumenterer, med 400 invalid_body, invalid_input eller invalid_coding_input. Decide ignorerer felter, det ikke kender.
• Chat og Coding bruger OpenAI's format for chat completions.
• Tekstlængder og positioner tæller UTF-16-kodeenheder, ligesom længden af en streng i JavaScript og .NET. I Python giver len(text.encode("utf-16-le")) // 2 det samme tal.
• Id'er som et tekstjobs id og organisation_id er UUID'er; id i et svar fra Chat begynder med chatcmpl-. Tidspunkter som createdAt og expiresAt er ISO 8601 i UTC. created i svar fra Chat og Coding er sekunder siden 1970 (UTC).
• Et kald, der lykkes, svarer 200, eller 202, når det har oprettet et tekstjob, eller når du beder om resultatet af et job, der stadig venter eller kører.
• Svar på kald med en nøgle har Cache-Control: private, no-store.
• Et kald, der fejler, svarer med en status og en fejl-body. Se Fejl.

Request-Id

Hvert svar på et kald, API'et behandler, har headeren Request-Id med et UUID, og en fejl-body gentager det som request_id. Log det med hvert kald, og oplys det, når du spørger komplai om et kald.

Vil du have dit eget id brugt, så send det i X-Request-Id. Det skal være ét gyldigt UUID; ved andre værdier laver API'et et nyt. Undtagelsen er POST /v1/coding/chat/completions, som kræver X-Request-Id og svarer 400 invalid_request_id uden den: et nyt UUID i version 4 til hver handling, og det samme igen kun, når du gentager en handling, hvis udfald du ikke kender. komplai svarer så 409 duplicate_request i stedet for at kalde modellen en gang til.

Et svar uden Request-Id blev givet, før API'et behandlede kaldet, fx af gatewayen, mens API'et genstarter. Behandl det ud fra dets status.

Nye forsøg og idempotens

Om du kan sende et kald igen, afhænger af, om det allerede kan have nået en model.

• Tekstjob. Send Idempotency-Key med et nyt UUID til hvert job på POST /v1/redact/jobs og POST /v1/redact/file/jobs og på POST /v1/redact og POST /v1/redact/file med Prefer: respond-async. Hvis forbindelsen afbrydes, så send samme kald med samme Idempotency-Key: Inden for jobbets levetid får du det samme job tilbage med reused true i stedet for et nyt job. Samme Idempotency-Key med en anden body svarer 409 idempotency_conflict. En Idempotency-Key er bundet til jeres organisation, ejeren af API-nøglen (en person eller en integration) og selve API-nøglen.
• Coding. X-Request-Id, som beskrevet ovenfor.
• Chat og synkron Redact har ingen idempotens. Et kald, der fik timeout eller mistede forbindelsen, kan allerede have nået modellen, og kald i EU-cloud tæller med i det månedlige loft for AI-forbrug. Send dem ikke igen automatisk, og slå automatiske nye forsøg med POST fra i din HTTP-klient eller dit SDK.
• Kald uden betaling for AI, der ikke ændrer noget, fx GET-operationer, POST /v1/redact/detect og POST /v1/redact/restore, kan sendes igen. Hvert kald tæller med i din grænse for kald.
• Efter 429 venter du det antal sekunder, der står i Retry-After. Fejl viser, hvornår et nyt forsøg hjælper.

Læs et tekstjobs status højst hvert andet sekund. Så længe jobbet venter eller kører, svarer GET /v1/redact/jobs/{id}/result 202 med Retry-After: 2.

Kald fra en browser

API'et tager kun imod kald fra browseren på komplais egne sites, også konsollerne på dette site. Kald det fra en server, et script eller en integrationsplatform: En nøgle på en webside kan ses af alle, der åbner den.

Prøv et kald

Hvert endpoint har en konsol, der sender kaldet fra din browser til API'et med en nøgle, du indsætter. Nøglen bliver i sidens hukommelse og glemmes, når du forlader siden; konsollen gemmer den aldrig i browseren. På developers.test.komplai.dk kalder konsollen testmiljøet.

Kaldene er rigtige: komplai behandler det, du sender, hvert kald tæller med i nøglens grænser, og behandling i EU-cloud tæller med i organisationens månedlige loft for AI-forbrug. Brug testdata.