Zilo-motoren som REST-API

1. Opret en API-nøgle

Gå til Indstillinger → API & MCP i Zilo (kræver ejer-rolle), og opret en nøgle. Den vises kun én gang - behandl den som en adgangskode. Nøglen giver adgang til hele organisationens analyser og dokumenter og kan tilbagekaldes med øjeblikkelig virkning. Samme nøgle virker i både API'et og ZILO MCP.

2. Kald API'et

curl https://zilo.dk/api/public/v1/analyses \
  -H "Authorization: Bearer zilo_DIN_NØGLE"

curl https://zilo.dk/api/public/v1/analyses/ANALYSE_ID/brief \
  -H "Authorization: Bearer zilo_DIN_NØGLE"

curl -X POST https://zilo.dk/api/public/v1/analyses/ANALYSE_ID/score \
  -H "Authorization: Bearer zilo_DIN_NØGLE" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Mit udkast\n\nTeksten der skal scores..."}'

Succes-svar er { data: ... } med id'er og tal plus et markdown-felt med den fulde rapport i læsbar form - klar til at sende videre til en sprogmodel eller vise i jeres eget værktøj uden at bygge visningen selv.

Workflowet

1. Start analysen. POST /analyses svarer 201 med et analysisId.
2. Vent til den er klar. Spørg GET /analyses/{id}, til status er ready - typisk 1-3 minutter.
3. Hent briefen. Termer, spørgsmål, entiteter og mållængde - alt det, teksten skal ramme.
4. Skriv og scor undervejs. Scoring er gratis og tæller ikke i kvoten, så kald den så tit, I vil.
5. Gem dokumentet med POST /drafts.

Når dokumentet allerede findes

Intet kald kan overskrive et dokument stiltiende. Derfor svarer to situationer med 409 i stedet:

• draft_exists - analysen har allerede et dokument. Svaret indeholder editorId: hent dokumentet med GET /drafts/{id} og opdatér det med PUT og den baseRev, I læste.
• conflict - dokumentet er ændret, siden I læste det. Svaret indeholder den aktuelle revision: hent, flet jeres ændringer ind, og prøv igen.

Endpoints

• GET /analyses - organisationens analyser med status og id
• POST /analyses - start en ny analyse (tæller i jeres kvote) - 201 + analysisId
• GET /analyses/{id} - status og fremdrift, mens analysen kører
• GET /analyses/{id}/brief - skrive-briefen: termer, spørgsmål, outline, GEO-facts - og kundens stemme, hvis sitet har en profil
• GET /voice-profiles - hvilke af jeres sites har en stemmeprofil
• POST /analyses/{id}/score - scor et markdown-udkast - SEO + GEO, uden at gemme
• POST /drafts - gem udkastet som Zilo-dokument med redigér- og delelink
• GET /drafts/{id} - hent et dokument som markdown med aktuel revision
• PUT /drafts/{id} - opdatér dokumentet sikkert (baseRev-revisionskontrol)

Scoring er gratis og tæller ikke i kvoten - betalingspunktet er analysen, præcis som i webappen. Hvert felt og hvert svar er beskrevet i detaljer i openapi.json.

Fejl og statuskoder

• 400 - invalid_input - ugyldigt input; beskeden siger hvad der er galt
• 401 - invalid_api_key - manglende, ugyldig eller tilbagekaldt nøgle
• 402 - quota_exceeded - analysekvoten er brugt; svar med forbrug og plan
• 404 - not_found - findes ikke i jeres organisation
• 409 - draft_exists / conflict / analysis_not_ready - tilstandskonflikter
• 429 - rate_limited - med Retry-After-header og retryAfterSeconds

Fejlkroppe er { error, message, ... } med danske, handlingsanvisende beskeder og relevante felter (fx currentRev ved konflikter).

Grænser og privatliv

• score: 30 kald/minut
• brief: 10 kald/minut
• create: 10 kald/minut + jeres analysekvote
• drafts (gem/opdatér): 20 kald/minut, udkast op til 100 KB

Grænserne er pr. nøgle pr. minut og gælder API'et og MCP hver for sig. Vi logger hvilket endpoint der blev kaldt, hvornår og hvor længe det tog - aldrig dine udkast eller argumenter. Tilbagekalder du en nøgle, virker den ikke ved næste kald.

Til udviklere

Versionering ligger i stien (/v1) - vi bryder ikke kontrakten uden nyt versionsnummer. CORS er bevidst slået fra: API'et er til server-side-kald, ikke browserkode (nøglen hører ikke hjemme i en klient). Analyser leveres asynkront via polling - webhooks kommer, når efterspørgslen viser sig. Mangler dit workflow et endpoint? Skriv til hej@zilo.dk.