GraphQL API Reference

GGNomad is GraphQL-first. Product state — destinations, listings (stays, tours, activities, events), availability, itineraries, bookings, trips, and reviews — is served over a single GraphQL endpoint. Every request is authenticated and permission-checked before any data is read or written.

Roadmap items

Operations marked roadmap are committed direction, not yet exposed.

Endpoint

All operations are sent as POST requests to the GGNomad GraphQL endpoint. The default is production. Set BURDENOFF_ENV=local|alpha|prod to switch:

BURDENOFF_ENV	Endpoint
prod (default)	https://graphqlworkspaces.burdenoff.com/workspaces/graphql
alpha	https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql
local	http://localhost:4003/workspaces/graphql

POST /workspaces/graphql
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

Every field is permission-checked and scoped to the caller's workspace — a query for inventory in another workspace returns nothing. The workspace comes from your authenticated session, never from a client-supplied argument.

Authentication

OAuth 2.0 / OIDC Interactive and service callers authenticate through single sign-on and send a bearer token:

Authorization: Bearer YOUR_OAUTH_TOKEN

API keys Automation and integration callers use a workspace-scoped API key issued from the developer portal:

Authorization: Bearer YOUR_API_KEY

Discovery & inventory

List properties (stays) Browse bookable stays in the workspace:

query Properties {
  ggnomadProperties(pagination: { skip: 0, take: 20 }) {
    id
    name
    location
    pricePerNight
    rating
    provider { id name type rating }
  }
}

Get a single listing Open a stay, tour, activity, or event by id:

query Property($id: ID!) {
  ggnomadProperty(id: $id) {
    id
    name
    description
    location
    pricePerNight
    amenities
    provider { id name rating }
  }
}

The same shape applies to tours (ggnomadTours / ggnomadTour(id)), activities (ggnomadActivities / ggnomadActivity(id)), and events (ggnomadEvents / ggnomadEvent(id)). Transport trips are read via ggnomadTrips.

Bookings & trips

Create a booking Confirm a reservation against a listing or an event. GGNomad generates a human-readable reference code (GG-{TYPE}-…), validates the target belongs to the caller's workspace, and emits a booking.created event:

mutation Book($input: CreateGgnomadBookingInput!) {
  createGgnomadBooking(input: $input) {
    id
    referenceCode
    status          # CONFIRMED
    paymentStatus   # PAID
    checkIn
    checkOut
  }
}

{
  "input": {
    "targetType": "PROPERTY",
    "targetId": "lst_…",
    "checkIn": "2026-08-14",
    "checkOut": "2026-08-17",
    "guests": 2
  }
}

List bookings Retrieve the caller's bookings, each on its own timeline:

query Bookings {
  ggnomadBookings {
    id
    referenceCode
    status
    target { __typename id name }
  }
}

Cancel a booking Move a booking to cancelled, with the transition recorded:

mutation Cancel($id: ID!) {
  cancelGgnomadBooking(id: $id) { id status }
}

Favorites & wishlist

Toggle a favorite Save inventory to (or remove it from) a wishlist — the precursor to building an itinerary:

mutation Favorite($targetType: GgnomadBookingType!, $targetId: ID!) {
  toggleGgnomadFavorite(targetType: $targetType, targetId: $targetId)
}

query Favorites {
  ggnomadFavorites
}

Hosts & operators

Onboard a provider Register a host or operator (a guesthouse, tour company, or venue):

mutation Provider($input: CreateGgnomadProviderInput!) {
  createGgnomadProvider(input: $input) { id name type rating }
}

Create a property listing Add a bookable stay under a provider:

mutation Listing($input: CreateGgnomadPropertyInput!) {
  createGgnomadProperty(input: $input) {
    id
    name
    location
    pricePerNight
  }
}

Analytics & overview Read marketplace and operator analytics:

query Overview {
  ggnomadOverviewStats { totalBookings totalRevenue occupancyRate }
  ggnomadAnalytics { categoryMix { category count } topProviders { id name } }
}

Roadmap operations

Destinations (GgnomadDestination), reviews (GgnomadReview), itinerary and unified multi-item checkout, and marketplace verification mutations are modelled in the product but are not yet exposed as GraphQL operations. They are committed roadmap — see Core Concepts and the product roadmap.

Error handling

GGNomad surfaces errors in the standard GraphQL errors array with a typed code in extensions:

{
  "errors": [
    {
      "message": "Workspace context required",
      "extensions": { "code": "WORKSPACE_REQUIRED" }
    }
  ]
}

Common codes

• UNAUTHENTICATED — no valid token
• FORBIDDEN — the actor lacks the required ggnomad:* permission
• WORKSPACE_REQUIRED — the request carried no workspace context
• NOT_FOUND — the target does not exist in this workspace
• VALIDATION_ERROR — the input failed schema or business validation

Rate limiting

Quotas are enforced per action, according to the workspace's billing plan. Limits surface as standard headers on the API response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1623456789

Best practices

• Request only the fields you need — GraphQL lets you select exactly the inventory, booking, and provider fields a screen requires
• Paginate list queries — every list query accepts a pagination argument
• Handle the typed error codes above rather than parsing messages
• Respect workspace scoping — never assume an id from one workspace resolves in another

Getting started

Begin with a read query (ggnomadProperties) to confirm connectivity and your token's ggnomad:read permission, then move on to booking flows. For the full schema and partner integration patterns, see the Developer Guide and API Reference Overview.