Bygg med Gjestfri

1. Kom igång på 60 sekunder

1. Logga in på app.gjestfri.com → Inställningar → API-nycklar
2. Tryck på ”Ny API-nyckel”. Välj namn och scopes (eller använd presetet ”MCP-server (allt)” för full tillgång).
3. Du ser nyckeln i klartext en enda gång. Kopiera den direkt och spara den i en lösenordshanterare eller som miljövariabler.
4. Testa:

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

2. Auth + scopes

Alla endpoints under /v1/* är Bearer-autentiserade. Auth-mekanismen kontrollerar prefixet:

• gf_live_… / gf_test_… → API-nyckel (rate-limitad per nyckel, scopes upprätthålls)
• Övrigt → JWT (intern webb/iOS, full tillgång)

Tillgängliga 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 innebär automatiskt :read.

Rate limit

60 requests/minut per nyckel som standard. Headers returneras på alla svar:

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

3. REST API-endpoints

Boenden

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

Bokningar

• GET /v1/bookings?propertyId&status&from&to&limit
• GET /v1/bookings/:id
• POST /v1/bookings - manuell direktbokning
• PATCH /v1/bookings/:id

Meddelanden

• GET /v1/messages/unread
• GET /v1/messages/by-booking/:id
• POST /v1/messages/by-booking/:id - skicka till gäst

Prissättning

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

Tillgänglighet

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

Städning

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

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

Exempel - lista bokningar

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 (chatt-API)

Agenten har full åtkomst till värdens data och 60+ tools (CRUD på boenden, bokningar, städning, priser, snabbsvar, kanaler, ...). Prata naturligt, agenten väljer rätt tool själv.

Endpoints

• POST /v1/agent/chat - skicka meddelande
• POST /v1/agent/confirm/:actionLogId - bekräfta väntande åtgärd
• GET /v1/agent/conversations
• GET /v1/agent/conversations/:id/messages
• GET/PATCH /v1/agent/settings

Exempel

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: koppla din AI-assistent till Gjestfri

Gjestfri har en fjärrbaserad MCP-server på https://api.gjestfri.com/mcp. Claude, ChatGPT, VS Code, Cursor och andra MCP-klienter ansluter med vanlig inloggning i Gjestfri och ett samtycke där du väljer tillgångsnivå. Ingen API-nyckel, inget att installera.

Assistenten ser och gör bara det du själv har tillgång till. Pengar, återbetalningar, avbokningar och radering kräver alltid en extra bekräftelse i assistenten. Tillgången kan återkallas när som helst under Inställningar, AI-assistenter.

Tre tillgångsnivåer vid samtycke

• Bara läsning: assistenten kan se, men inte ändra något.
• Daglig drift: läsa allt, och skriva i meddelanden, bokningar, priser, städning, uppgifter och boenden. Inte pengar, förvaltning eller konto.
• Full tillgång: allt du själv kan göra i Gjestfri.

Claude.ai och Claude Desktop

Inställningar, Kopplingar (Connectors), ”Lägg till anpassad koppling”. Klistra in adressen, logga in och godkänn:

https://api.gjestfri.com/mcp

Claude Code

Kör kommandot nedan och skriv /mcp i Claude Code för att logga in:

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

ChatGPT

Inställningar, Kopplingar (Connectors), slå på utvecklarläge (Developer mode) och välj ”Skapa”. Klistra in samma adress. ChatGPT använder samma inloggning och samtycke.

VS Code och GitHub Copilot

Lägg det här i .vscode/mcp.json i projektet, eller i den globala mcp.json:

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

Cursor och andra klienter

Cursor läser .cursor/mcp.json med nyckeln mcpServers. Alla klienter som stöder Streamable HTTP och OAuth 2.1 med dynamisk registrering eller klientmetadata (CIMD) kan ansluta:

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

Verktygen (utdrag)

Gjestfrid har 202 verktyg, och 195 av dem är tillgängliga över MCP för en ägare med full tillgång, utöver whoami, confirm_action och cancel_action. Katalogen filtreras efter roll och tillgångsnivå, så en städare eller ägare ser bara sitt. Din klient visar hela listan.

För dig som bygger en klient

• Transport: Streamable HTTP med JSON-svar, bara POST. Inloggning: OAuth 2.1 med PKCE (S256), dynamisk registrering på /oauth/register och klientmetadatadokument (CIMD) som klient-id.
• Upptäckt: /.well-known/oauth-protected-resource/mcp och /.well-known/oauth-authorization-server på api.gjestfri.com. Åtkomsttoken gäller en timme, refresh-token 90 dagar.
• Saknar tokenet ett område svarar servern 403 med insufficient_scope, så att klienten kan be om nytt samtycke. Resurser och prompter kommer senare. Områdena:

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-notiser när något händer. HMAC-SHA256-signerad payload. Max 3 retries med exponentiell backoff.

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

Tillgängliga events

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

Verifiera signaturen

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

7. Meddelandekanaler (värd ↔ agent)

Agenten kan nås via iMessage/RCS/SMS, Telegram eller WhatsApp. Endpoints för att koppla och hantera kanaler:

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

POST returnerar en deeplink (Telegram/WhatsApp) eller skickar ett iMessage med en kod på 6 tecken. Värden verifierar genom att öppna deeplinken eller svara med koden.

8. Gäst-MCP (kommer)

En egen MCP-ingång för resenärers assistenter, som söker, bokar och följer upp vistelsen, är planerad som fjärrtjänst med åtkomstkod per bokning. Paketet @gjestfri/mcp-guest är inte publicerat, och det finns ingen guide ännu. Skriv till utviklere@gjestfri.com om du vill vara tidigt ute.

Hjälp och kontakt

• Frågor: utviklere@gjestfri.com
• Vanliga frågor: /faq
• Status: api.gjestfri.com (returnerar 200 + version)