KVEO DIGITAL API

Kundedokumentasjon for Kveo API

Dette er den sentrale dokumentasjonen for eksterne kundesystem som skal snakke med Kveo Panel. API-et er versjonert, token-basert og isolerer alltid data per kunde.

OpenAPI JSON Sjå endepunkt

Start

Base URL for eksterne kundesystem er https://kveo.no/api/v1. Interne admin-ruter i Kveo Panel skal ikkje brukast av kundesystem.

Status: API-et er i produksjon, inkludert AI-request proxyen (/ai/messages, scope ai:use) med full kostnadskontroll og kredittrekk. Bowlit er ikkje kopla på enno.

Autentisering

Alle kundespesifikke kall brukar server-to-server token i Authorization-headeren. Kunden blir bestemt frå tokenet, ikkje frå request body eller query-parametrar.

curl https://kveo.no/api/v1/customer \
  -H "Authorization: Bearer yrm_st_..."

Token blir generert sikkert og vist berre ein gong ved oppretting.
Berre SHA-256 hash av tokenet blir lagra i databasen.
Token kan deaktiverast, roterast og ha utløpsdato.
last_used_at blir oppdatert ved gyldige kall.

Scopes

ai:readai:useai:topupbilling:readinvoices:readsupport:readsupport:writestatus:readsms:sendsms:read

Scope blir kontrollert per endepunkt. Manglande scope gir 403.

Endepunkt

GET/api/v1/customer

Return safe customer profile for the token owner.

Responskodar: 200, 401

GET/api/v1/services

List services for the token owner.

Responskodar: 200, 401

GET/api/v1/ai

Return AI credit and usage status.

Required scope: ai:read. Also returns any credit requests that are still waiting to be handled by Kveo.Responskodar: 200, 401, 403

GET/api/v1/ai/credit-requests

List requests for extra AI credit.

Required scope: ai:read. Filter with ?status=pending|approved|rejected.Responskodar: 200, 400, 401, 403

POST/api/v1/ai/credit-requests

Ask Kveo to invoice you for extra AI credit.

Required scope: ai:topup. Use this when the AI credit included in your monthly plan is spent. The request does not add credit by itself: Kveo invoices the amount and approves the request, and the credit appears on your balance at that point. Send the same "reference" when retrying so a retry never turns into two invoices.Responskodar: 200, 201, 400, 401, 403, 409

GET/api/v1/ai/credit-requests/{id}

Return one credit request.

Required scope: ai:readResponskodar: 200, 401, 403, 404

POST/api/v1/ai/messages

Send a message to Claude (Anthropic) through Kveo's AI gateway.

Required scope: ai:use. The model is fixed per customer by Kveo and cannot be chosen in the request. Mirrors the shape of Anthropic's own Messages API.Responskodar: 201, 400, 401, 402, 403, 502

GET/api/v1/invoices

List invoices visible to this customer.

Required scope: invoices:readResponskodar: 200, 401, 403

GET/api/v1/support/tickets

List support tickets for this customer.

Required scope: support:readResponskodar: 200, 401, 403

POST/api/v1/support/tickets

Create a support ticket for this customer.

Required scope: support:writeResponskodar: 201, 400, 401, 403, 404

POST/api/v1/sms/send

Send an SMS through Kveo's SMS gateway using your configured sender ID.

Required scope: sms:send. The sender ID is fixed per customer by Kveo and cannot be overridden in the request.Responskodar: 201, 400, 401, 403, 502

GET/api/v1/sms/log

List recent SMS sent through the gateway for this customer.

Required scope: sms:readResponskodar: 200, 401, 403

GET/api/v1/status

Return service status for this customer.

Required scope: status:readResponskodar: 200, 401, 403

Eksempel

Opprette supportsak

curl https://kveo.no/api/v1/support/tickets \
  -H "Authorization: Bearer yrm_st_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Problem med AI-svar","body":"Beskriv saka her","priority":"normal"}'

AI-status respons

{
  "ai": {
    "enabled": true,
    "included_credit_remaining": 72.4,
    "purchased_credit": 250,
    "total_available_credit": 322.4,
    "current_month_usage": 27.6,
    "current_month_limit": 500,
    "month": "2026-08"
  }
}

Be om faktura på meir AI-kreditt

Er den inkluderte månadskreditten brukt opp, svarar /ai/messages med 402 credit_exhausted. Då kan systemet be om ein faktura på meir kreditt (scope ai:topup). Kallet gir ikkje kreditt med ein gong. Kveo fakturerer beløpet og godkjenner førespurnaden, og krediten dukkar opp på saldoen då. Send same reference ved retry, så blir det aldri to fakturaer av same ynske.

curl https://kveo.no/api/v1/ai/credit-requests \
  -H "Authorization: Bearer yrm_st_..." \
  -H "Content-Type: application/json" \
  -d '{"amount_nok":500,"note":"Auto-svar i september","reference":"2026-09-01"}'

Datamodellar

Customer

UUID, namn, organisasjonsnummer, kundenummer, e-post og aktiv-status.

Customer service

Tenestetype, namn, status og JSON-config, til dømes inkludert månadleg AI-kreditt.

Service token

Hashed token, scopes, aktiv-status, last_used_at, expires_at og rotasjonsspor.

AI ledger

Transaksjonar for monthly_included, usage, manual_adjustment, invoice_topup, refund og expiry.

AI credit request

Kunden sitt ynske om ein faktura på meir kreditt: beløp, notat, eigen referanse, status (pending/approved/rejected) og fakturareferanse.

AI usage

Provider, modell, tokenbruk, kostnad, valuta, request_id og tidspunkt.

Invoice

Fiken/Stripe/Kveo-fakturaer med status, beløp, datoar og PDF/hosted URL der det finst.

Support ticket

Tittel, status, prioritet, service/resource-kopling og svartråd.

Status event

Status per kundeteneste med melding, start og eventuell slutt.

Audit log

Actor, customer_id, action, metadata og timestamp for sensitive handlingar.

Feilkodar

Status	Når
`400`	Ugyldig request body eller valideringsfeil.
`401`	Manglande, ugyldig, deaktivert eller utløpt token.
`403`	Tokenet manglar nødvendig scope.
`402`	AI-krediten er brukt opp. Be om meir med POST /ai/credit-requests.
`404`	Ressursen finst ikkje for denne kunden.
`409`	For mange ubehandla kredittførespurnader ligg alt og ventar.
`429`	Rate limit er nådd. Sjå X-RateLimit-headerar.
`500`	Uventa serverfeil. Secrets blir ikkje returnert i responsen.

Sikkerheit og drift

Eksterne system skal aldri sende customer_id; kundeidentitet kjem frå service-token.
OpenAI- og Fiken-credentials ligg berre server-side i Kveo Panel.
Ingen API-responsar returnerer bearer token, API-nøklar eller Fiken credentials.
Sensitive handlingar blir logga i audit-logg.
Request bodies blir validerte server-side før data blir lagra.