Build with Gjestfri

1. Get started in 60 seconds

1. Sign in at app.gjestfri.com → Settings → API keys
2. Click “New API key”. Pick a name and scopes (or use the “MCP server (everything)” preset for full access).
3. You see the plaintext key once - copy it right away and store it in a password manager or env variables.
4. Test it:

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

2. Auth + scopes

All endpoints under /v1/* use Bearer authentication. The auth layer checks the prefix:

• gf_live_… / gf_test_… → API key (rate-limited per key, scope-enforced)
• Anything else → JWT (internal web/iOS, full access)

Available 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 automatically implies :read.

Rate limit

60 requests per minute per key by default. Headers are returned on every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
Retry-After: 23  (only on 429)

3. REST API endpoints

Properties

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

Bookings

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

Messages

• GET /v1/messages/unread
• GET /v1/messages/by-booking/:id
• POST /v1/messages/by-booking/:id - send to guest

Pricing

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

Availability

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

Cleaning

• 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

Example - list bookings

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)

The agent has full access to the host's data and 60+ tools (CRUD on properties, bookings, cleaning, rates, quick replies, channels, ...). Talk to it naturally - the agent picks the right tool on its own.

Endpoints

• POST /v1/agent/chat - send a message
• POST /v1/agent/confirm/:actionLogId - confirm a pending action
• GET /v1/agent/conversations
• GET /v1/agent/conversations/:id/messages
• GET/PATCH /v1/agent/settings

Example

curl https://api.gjestfri.com/v1/agent/chat \
  -H "Authorization: Bearer gf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What needs my attention today?",
    "channel": "ios"
  }'

# →
# {
#   "conversationId": 42,
#   "reply": "3 things: Anna checks in at 4 PM - welcome message not sent. ...",
#   "toolCalls": [
#     { "name": "list_unread_messages", "result": { ... } }
#   ]
# }

5. MCP for AI agents

Connect Claude Desktop, Cursor, or any other MCP-compatible agent directly to Gjestfri. The agent gets access to all your properties, bookings, and 60+ tools.

Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Cursor / other MCP clients

Same setup. Cursor keeps its MCP config under Settings → MCP. Point it to npx @gjestfri/mcp-server with the same env variable.

Available tools (excerpt)

60+ tools in total. The complete catalog shows up in your client once MCP is connected.

Resources (gjestfri:// URIs)

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

6. Webhooks

Get push notifications when something happens. HMAC-SHA256 signed payloads. Up to 3 retries with exponential backoff.

Register a subscription

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

# The response includes the secret only on creation:
# { "id": 12, "secret": "whsec_...", "events": [...] }

Available events

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

Verify the signature

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

7. Messaging channels (host ↔ agent)

You can talk to the agent over iMessage/RCS/SMS, Telegram, or WhatsApp. Endpoints for connecting and managing channels:

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

POST returns a deep link (Telegram/WhatsApp) or sends an iMessage with a 6-character code. The host verifies by opening the deep link or replying with the code.

8. Guest MCP (booking side)

A separate MCP server for AI agents that book on behalf of travelers. No API key needed for search - auth via a per-booking access code after payment.

{
  "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.

Help and contact

• Questions: utviklere@gjestfri.com
• FAQ: /faq
• Status: api.gjestfri.com (returns 200 + version)