Bygg med Gjestfri

1. Kom i gang på 60 sekunder

1. Logg inn på app.gjestfri.com → Innstillinger → API-nøkler
2. Trykk «Ny API-nøkkel». Velg navn og scopes (eller bruk «MCP-server (alt)»-presetet for full tilgang).
3. Du ser plaintext-nøkkelen én gang — kopier den med en gang og lagre i passordhåndterer eller env-variabler.
4. Test:

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

2. Auth + scopes

Alle endepunkter under /v1/* er Bearer-autentisert. Auth-mekanismen sjekker prefikset:

• gf_live_… / gf_test_… → API-key (rate-limited per nøkkel, scope-håndhevet)
• Annet → JWT (intern web/iOS, full tilgang)

Tilgjengelige 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 impliserer :read automatisk.

Rate limit

60 requests/minutt per nøkkel som standard. Headere returneres på alle responser:

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

3. REST API endepunkter

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 — manuell direkte-booking
• PATCH /v1/bookings/:id

Meldinger

• GET /v1/messages/unread
• GET /v1/messages/by-booking/:id
• POST /v1/messages/by-booking/:id — send til gjest

Prising

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

Tilgjengelighet

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

Vask

• 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-keys

• 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 full tilgang til vertens data og 60+ tools (CRUD på boliger, bookinger, vask, priser, hurtigsvar, kanaler, ...). Snakk naturlig — agenten velger riktig tool selv.

Endepunkter

• POST /v1/agent/chat — send melding
• POST /v1/agent/confirm/:actionLogId — bekreft pending 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 for AI-agenter

Koble Claude Desktop, Cursor eller en annen MCP-kompatibel agent direkte til Gjestfri. Agenten får tilgang til alle dine boliger, bookinger og 60+ verktøy.

Claude Desktop

Legg dette i ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gjestfri": {
      "command": "npx",
      "args": ["-y", "@gjestfri/mcp-server"],
      "env": {
        "GJESTFRI_API_KEY": "gf_live_..."
      }
    }
  }
}

Cursor / andre MCP-klienter

Samme oppsett. Cursor har MCP-config under Settings → MCP. Pek til npx @gjestfri/mcp-server med samme env-variabel.

Tilgjengelige tools (utdrag)

Totalt 60+ tools. Komplett katalog vises i klienten din når MCP er koblet til.

Resources (gjestfri:// URI-er)

gjestfri://properties
gjestfri://properties/{id}
gjestfri://properties/{id}/calendar
gjestfri://bookings/{id}
gjestfri://bookings/{id}/messages
gjestfri://messages/unread

6. Webhooks

Få push-notifikasjoner når noe skjer. HMAC-SHA256 signert payload. Maks 3 retries med eksponentiell backoff.

Registrer 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": [...] }

Tilgjengelige events

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

Verifiser signaturen

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

7. Meldingskanaler (vert ↔ agent)

Agenten kan snakkes med via iMessage/RCS/SMS, Telegram eller WhatsApp. Endepunkter for å koble og administrere kanaler:

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

POST returnerer en deeplink (Telegram/WhatsApp) eller sender en iMessage med en 6-tegns kode. Vert verifiserer ved å åpne deeplinken eller svare med koden.

8. Guest MCP (booking-side)

En separat MCP-server for AI-agenter som booker på vegne av reisende. Ingen API-key nødvendig for søk — auth via per-booking access-code etter betaling.

{
  "mcpServers": {
    "gjestfri-guest": {
      "command": "npx",
      "args": ["-y", "@gjestfri/mcp-guest"]
    }
  }
}

Tools: search_properties, get_property_details, check_availability, start_booking, get_my_booking, send_message_to_host.

Hjelp og kontakt

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