# API-reference

> Adresser, versioner, OpenAPI-dokumentet, JSON-konventioner, request-id'er og nye forsøg samt alle endpoints i komplais API med en konsol, hvor du kan prøve dem.

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

```bash
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](https://developers.komplai.dk/da/authentication) 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

| Miljø | API | Nøgler fra |
| --- | --- | --- |
| Produktion | `https://api.komplai.dk` | `https://hub.komplai.dk` |
| Test | `https://api.test.komplai.dk` | `https://hub.test.komplai.dk` |

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](https://developers.komplai.dk/da/changelog) 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](https://developers.komplai.dk/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:

| Udvidelse | Indhold |
| --- | --- |
| `x-komplai-scopes` | De scopes, en operation kræver. |
| `x-komplai-principals` | De slags nøgler, en operation accepterer: `person` for en personlig API-nøgle, `integration` for organisationens integrationsnøgle. |
| `x-komplai-stability` | `stable`, `beta` eller `alpha` på hver operation og tag, `preview` på et felt i et kald. |
| `x-komplai-error-codes` | I roden: alle fejlkoder med deres statusser, betydning, hvad du kan gøre, deres side og de operationer, der returnerer dem. |

### Importér i Postman

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

1. Importér samlingen og miljøet i Postman, og vælg miljøet. Til et andet værktøj bruger du OpenAPI-dokumentet.
2. Sæt din nøgle ind i `token`. Til testmiljøet sætter du `baseUrl` til `https://api.test.komplai.dk`.
3. Send GET /v1/access for at se, at nøglen virker.

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`](https://developers.komplai.dk/da/errors/invalid_body), [`invalid_input`](https://developers.komplai.dk/da/errors/invalid_input) eller [`invalid_coding_input`](https://developers.komplai.dk/da/errors/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](https://developers.komplai.dk/da/errors).

## 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`](https://developers.komplai.dk/da/errors/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`](https://developers.komplai.dk/da/errors/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`](https://developers.komplai.dk/da/errors/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](https://developers.komplai.dk/da/errors) 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.

---

https://developers.komplai.dk/da/api