API Reference Overview
GGNomad exposes a GraphQL-first API that gives programmatic access to the whole travel journey — discovering destinations and listings, building itineraries, confirming bookings, following trips, and reading host and marketplace analytics. Every call is authenticated, permission-checked, and scoped to the caller's workspace before it runs.
Operations flagged as roadmap are committed direction, not yet exposed.
Environment selection
The API defaults to production. Set BURDENOFF_ENV=local|alpha|prod to
target a different environment:
BURDENOFF_ENV | Workspace gateway | Global gateway |
|---|---|---|
prod (default) | https://graphqlworkspaces.burdenoff.com/workspaces/graphql | https://graphql.burdenoff.com/global/graphql |
alpha | https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql | https://alphagraphql.burdenoff.com/global/graphql |
local | http://localhost:4003/workspaces/graphql | http://localhost:4000/global/graphql |
API surface
📊 GraphQL API
Flexible queries and mutations for inventory, bookings, trips, favorites, and analytics — request exactly the fields you need.
🔗 One endpoint
Inventory, bookings, identity, billing, files, conversations, and tags are all reachable from a single API endpoint.
📣 Events
Domain events such as booking.created are published for downstream automation and integrations.
Core concepts
Authentication Security
Every request is authenticated before any data is returned:
- OAuth 2.0 / OIDC bearer tokens for interactive and service callers
- Workspace-scoped API keys for automation and integrations
- OAuth device-code for terminal clients
- Enterprise SSO through your identity provider
Rate limiting Usage
Quotas are enforced per action, according to your billing plan:
- Per-workspace request quotas
- Booking and listing volume limits
- Usage tracking and metering
- Standard
X-RateLimit-*response headers
Error handling Reliability
Errors arrive in the GraphQL errors array with a typed code in extensions:
UNAUTHENTICATED/FORBIDDENWORKSPACE_REQUIREDNOT_FOUNDVALIDATION_ERROR
API categories
🧭 Discovery & inventory
Read the marketplace's supply:
- Properties / stays (
ggnomadProperties) - Tours, activities, and events
- Transport trips
- Providers / hosts
🛎️ Bookings & trips
Confirm and manage reservations:
- Create and cancel bookings
- List bookings and their timelines
- Toggle favorites / wishlist
- Host analytics and marketplace overview
API features
Response shape Data
- Typed GraphQL objects
- Field-level selection
- Pagination on every list query
- Workspace-scoped results
Versioning Schema
- Versionless schema evolution — no dated API versions to chase
- Additive, non-breaking changes by default
- Deprecation directives on retiring fields
- Migration guidance for breaking changes
Usage guide
🎯 Quick start
Start with a read query to confirm connectivity, then move to booking flows.
🔧 Best practices
Select only the fields you need, paginate lists, and handle typed error codes.
Our team is ready to help travel, tourism, and entertainment businesses build on the GGNomad API. Contact API support