Byg med Gjestfri

1. Kom i gang på 60 sekunder

1. Log ind på app.gjestfri.com → Indstillinger → API-nøgler
2. Tryk på »Ny API-nøgle«. Vælg navn og scopes (eller brug presettet »MCP-server (alt)« for fuld adgang).
3. Du ser nøglen i klartekst én gang. Kopiér den med det samme, og gem den i en password manager eller i miljøvariabler.
4. Test:

curl https://api.gjestfri.com/v1/properties \
  -H "Authorization: Bearer gf_live_..."

2. Auth + scopes

Alle endpoints under /v1/* er Bearer-autentificerede. Auth-mekanismen tjekker præfikset:

• gf_live_… / gf_test_… → API-nøgle (rate-limited pr. nøgle, scope-håndhævet)
• Andet → JWT (intern web/iOS, fuld adgang)

Tilgængelige scopes

properties:read    properties:write
bookings:read      bookings:write
messages:read      messages:write
pricing:read       pricing:write
availability:read  availability:write
cleaning:read      cleaning:write
analytics:read
webhooks:manage
agent:chat

:write indebærer automatisk :read.

Rate limit

60 requests pr. minut pr. nøgle som standard. Headere returneres på alle svar:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
Retry-After: 23  (kun ved 429)

3. REST API-endpoints

Boliger

• GET /v1/properties
• GET /v1/properties/:id
• PATCH /v1/properties/:id
• GET /v1/properties/:id/calendar?from&to

Bookinger

• GET /v1/bookings?propertyId&status&from&to&limit
• GET /v1/bookings/:id
• POST /v1/bookings - manuel direkte booking
• PATCH /v1/bookings/:id

Beskeder

• GET /v1/messages/unread
• GET /v1/messages/by-booking/:id
• POST /v1/messages/by-booking/:id - send til gæst

Prissætning

• GET /v1/pricing/recommendations?propertyId&from&to
• POST /v1/pricing/overrides
• DELETE /v1/pricing/overrides
• GET/PUT /v1/pricing/config

Tilgængelighed

• POST /v1/availability/block
• POST /v1/availability/unblock

Rengøring

• GET /v1/cleaning-tasks?status
• PATCH /v1/cleaning-tasks/:id

Analytics

• GET /v1/analytics/occupancy?from&to&propertyId
• GET /v1/analytics/revenue?from&to&propertyId

Webhooks + API-nøgler

• GET/POST/DELETE /v1/webhooks
• GET/POST/DELETE /v1/api-keys

Eksempel: list bookinger

curl 'https://api.gjestfri.com/v1/bookings?from=2026-06-01&limit=20' \
  -H "Authorization: Bearer gf_live_..."

# →
# {
#   "data": [
#     {
#       "id": 408,
#       "propertyId": 12,
#       "status": "confirmed",
#       "guest": { "name": "Anna M.", "country": "NO" },
#       "checkin": "2026-06-15",
#       "checkout": "2026-06-18",
#       "pricing": { "totalPrice": "4200", ... }
#     }
#   ]
# }

4. AI-agent (chat-API)

Agenten har fuld adgang til værtens data og 60+ tools (CRUD på boliger, bookinger, rengøring, priser, hurtigsvar, kanaler, ...). Tal naturligt, så vælger agenten selv det rigtige tool.

Endpoints

• POST /v1/agent/chat - send besked
• POST /v1/agent/confirm/:actionLogId - bekræft afventende handling
• GET /v1/agent/conversations
• GET /v1/agent/conversations/:id/messages
• GET/PATCH /v1/agent/settings

Eksempel

curl https://api.gjestfri.com/v1/agent/chat \
  -H "Authorization: Bearer gf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hva trenger oppmerksomhet i dag?",
    "channel": "ios"
  }'

# →
# {
#   "conversationId": 42,
#   "reply": "3 ting: Anna sjekker inn kl 16 - velkomst ikke sendt. ...",
#   "toolCalls": [
#     { "name": "list_unread_messages", "result": { ... } }
#   ]
# }

5. MCP: tilslut din AI-assistent til Gjestfri

Gjestfri har en fjernbaseret MCP-server på https://api.gjestfri.com/mcp. Claude, ChatGPT, VS Code, Cursor og andre MCP-klienter tilslutter sig med almindeligt login i Gjestfri og et samtykke, hvor du vælger adgangsniveau. Ingen API-nøgle, intet at installere.

Assistenten ser og gør kun det, du selv har adgang til. Penge, refusioner, afbestillinger og sletning kræver altid en ekstra bekræftelse i assistenten. Adgangen kan trækkes tilbage når som helst under Indstillinger, AI-assistenter.

Tre adgangsniveauer ved samtykke

• Kun læsning: assistenten kan se, men ikke ændre noget.
• Daglig drift: læse alt og skrive i beskeder, bookinger, priser, rengøring, opgaver og boliger. Ikke penge, forvaltning eller konto.
• Fuld adgang: alt det, du selv kan gøre i Gjestfri.

Claude.ai og Claude Desktop

Indstillinger, Forbindelser (Connectors), »Tilføj brugerdefineret forbindelse«. Indsæt adressen, log ind, og godkend:

https://api.gjestfri.com/mcp

Claude Code

Kør kommandoen herunder, og skriv /mcp i Claude Code for at logge ind:

claude mcp add --transport http gjestfri https://api.gjestfri.com/mcp

ChatGPT

Indstillinger, Forbindelser (Connectors), slå udviklertilstand (Developer mode) til, og vælg »Opret«. Indsæt samme adresse. ChatGPT bruger samme login og samtykke.

VS Code og GitHub Copilot

Læg dette i .vscode/mcp.json i projektet eller i den globale mcp.json:

{
  "servers": {
    "gjestfri": { "type": "http", "url": "https://api.gjestfri.com/mcp" }
  }
}

Cursor og andre klienter

Cursor læser .cursor/mcp.json med nøglen mcpServers. Alle klienter, der understøtter Streamable HTTP og OAuth 2.1 med dynamisk registrering eller klientmetadata (CIMD), kan tilslutte sig:

{
  "mcpServers": {
    "gjestfri": { "url": "https://api.gjestfri.com/mcp" }
  }
}

Værktøjerne (uddrag)

Gjestfrid har 202 værktøjer, og 195 af dem er tilgængelige over MCP for en ejer med fuld adgang, ud over whoami, confirm_action og cancel_action. Kataloget filtreres efter rolle og adgangsniveau, så en rengøringshjælp eller ejer kun ser sit eget. Din klient viser hele listen.

Til dig, der bygger en klient

• Transport: Streamable HTTP med JSON-svar, kun POST. Login: OAuth 2.1 med PKCE (S256), dynamisk registrering på /oauth/register og klientmetadata-dokumenter (CIMD) som klient-id.
• Discovery: /.well-known/oauth-protected-resource/mcp og /.well-known/oauth-authorization-server på api.gjestfri.com. Access token gælder én time, refresh token 90 dage.
• Mangler tokenet et scope, svarer serveren 403 med insufficient_scope, så klienten kan bede om nyt samtykke. Ressourcer og prompter kommer senere. Scopes:

properties:read   properties:write
bookings:read     bookings:write
messages:read     messages:write
pricing:read      pricing:write
cleaning:read     cleaning:write
payments:read     payments:write
finance:read
owners:read       owners:write
tasks:read        tasks:write
account:read      account:write
admin:read        admin:write

6. Webhooks

Få push-notifikationer, når der sker noget. HMAC-SHA256-signeret payload. Maks. 3 retries med eksponentiel backoff.

Registrér en subscription

curl https://api.gjestfri.com/v1/webhooks \
  -H "Authorization: Bearer gf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://din-server.no/webhook",
    "events": ["booking.created", "message.received"]
  }'

# Response inneholder secret kun ved opprettelse:
# { "id": 12, "secret": "whsec_...", "events": [...] }

Tilgængelige events

• booking.created, booking.updated, booking.cancelled
• message.received, message.sent
• cleaning.scheduled, cleaning.completed
• pricing.recommendation_changed
• agent.action_pending_confirmation

Verificér signaturen

// Header: X-Gjestfri-Signature: t=1234567890,v1=abc123...
const expected = crypto
  .createHmac("sha256", secret)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");

7. Beskedkanaler (vært ↔ agent)

Du kan tale med agenten via iMessage/RCS/SMS, Telegram eller WhatsApp. Endpoints til at tilslutte og administrere kanaler:

• GET /v1/host-channels
• POST /v1/host-channels - body: {channel, phoneNumber?}
• DELETE /v1/host-channels/:id

POST returnerer et deeplink (Telegram/WhatsApp) eller sender en iMessage med en 6-tegns kode. Værten verificerer ved at åbne deeplinket eller svare med koden.

8. Gæste-MCP (kommer)

En egen MCP-indgang til rejsendes assistenter, som søger, booker og følger op på opholdet, er planlagt som fjerntjeneste med adgangskode pr. booking. Pakken @gjestfri/mcp-guest er ikke udgivet, og der findes ingen opskrift endnu. Skriv til utviklere@gjestfri.com, hvis du vil være tidligt ude.

Hjælp og kontakt

• Spørgsmål: utviklere@gjestfri.com
• Ofte stillede spørgsmål: /faq
• Status: api.gjestfri.com (returnerer 200 + version)