An API for trips that have to work on the day

Quick start

Three calls: get a token, solve a day, and listen for what happens next. Every example runs against the sandbox once you have credentials.

1. Get an access token

Server-to-server integrations use the OAuth 2.0 client credentials grant. Tokens last an hour; request only the scopes you need.

curl -X POST https://api.novadventure.com/v1/oauth/token \
  -u "$NOVA_CLIENT_ID:$NOVA_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope="routes:write quotes:write bookings:read"

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "routes:write quotes:write bookings:read"
}

For back-office scripts, an API key works too. Send it as a bearer token. Keys are bound to one environment: a sandbox key is refused by production, and the reverse.

2. Solve a day

Send the stops and the traveler’s limits. You get back a feasible schedule, with a reason for every placement.

curl -X POST https://api.novadventure.com/v1/routes \
  -H "Authorization: Bearer $NOVA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8c1f2a7e-5d3b-4e0a-9f61-2b7d4c9a0e13" \
  -d '{
    "date": "2026-11-14",
    "start": { "lat": 35.687, "lng": -105.938, "time": "08:30" },
    "travelers": [{ "energy_budget": "moderate", "max_walk_km": 8 }],
    "stops": [
      { "product_id": "prd_sbx_mesa_hike", "duration_min": 150, "exposure": "high" },
      { "product_id": "prd_sbx_pottery_studio", "duration_min": 90 },
      { "product_id": "prd_sbx_cooking_class", "fixed_start": "17:30" }
    ],
    "weather": "forecast"
  }'

{
  "id": "rte_7Kq2mW",
  "version": 1,
  "status": "feasible",
  "schedule": [
    { "start": "08:30", "product_id": "prd_sbx_mesa_hike",
      "reason": "Exposed trail placed first; storm cells forecast after 13:40." },
    { "start": "12:15", "type": "meal",
      "reason": "Lunch near the studio keeps the next leg under 15 minutes." },
    { "start": "13:45", "product_id": "prd_sbx_pottery_studio",
      "reason": "Indoor stop placed in the storm window." },
    { "start": "17:30", "product_id": "prd_sbx_cooking_class",
      "reason": "Fixed start kept." }
  ],
  "energy": { "budget": "moderate", "used": 0.74 },
  "warnings": []
}

3. Listen for changes

Register an endpoint and we’ll POST events as they happen: signed, retried, and safe to process twice.

curl -X POST https://api.novadventure.com/v1/webhooks \
  -H "Authorization: Bearer $NOVA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ops.internal/nova/events",
    "events": ["route.replanned", "booking.confirmed", "booking.exception"]
  }'

{
  "id": "evt_3Rb81x",
  "type": "route.replanned",
  "created": "2026-11-14T20:41:07Z",
  "data": {
    "route_id": "rte_7Kq2mW",
    "version": 2,
    "trigger": "weather.storm_cell",
    "status": "awaiting_approval"
  }
}

Each delivery carries a Nova-Signature header, an HMAC-SHA256 of the timestamp and raw body made with your endpoint’s signing secret. Verify it, reject anything older than five minutes, and use the event id to ignore duplicates. Failed deliveries retry with exponential backoff for 24 hours.

Re-plans arrive as awaiting_approval by default. Your product, or a person on your team, confirms them with POST /v1/routes/{id}/versions/{version}/approve. We draft; you decide.

MCP for AI agents

Agent Gateway exposes a curated set of tools over the Model Context Protocol at https://api.novadventure.com/v1/mcp, scoped to your own catalog.

Tool	What it does	Default
search_products	Find bookable products by place, date, interests and access needs	On
check_availability	Live availability and total price for a product and party	On
plan_day	Route a day through the Route Engine, with reasons	On
create_quote	Price and hold a plan for a short window	Off
request_booking	Book a held quote after explicit traveler confirmation	Off

Write tools stay off until you enable them, with spending limits and confirmation rules you set. Every tool call is logged with the calling agent and attributed through to any booking it leads to.

Errors

Errors share one shape everywhere, with a stable type to branch on and a request_id to quote to support@novadventure.com.

{
  "error": {
    "type": "constraint_conflict",
    "message": "prd_sbx_cooking_class has a fixed start at 17:30 that cannot be reached within the traveler's walking limit.",
    "request_id": "req_9Fh2Lp"
  }
}