canonical: https://jentic.com/apis/furkot.com/furkot

# Furkot Trips

The Furkot Trips API exposes programmatic access to multi-day road-trip itineraries built in the Furkot trip planner, focusing on creating and updating trips and synchronising the stop list including skipped stops. The API is OAuth 2.0 protected with both authorization-code and implicit flows, so third-party apps can act on behalf of Furkot users without handling passwords. The three current endpoints cover trip-level operations and stop-level mutations, returning Furkot's structured trip and stop models that include geocoded waypoints, dates, and ordering. The service is targeted at travel apps, RV planners, and itinerary tools that want to push or pull Furkot road-trip data alongside their own content.

## For AI agents

Create and update Furkot road-trip itineraries and synchronise their ordered stop lists, including skipped stops, on behalf of authenticated users via OAuth 2.0.

## Scope

Does not handle live navigation, hotel booking, or fuel-price lookups - use for Furkot trip and stop synchronisation only.

## Capabilities

- Create or update a multi-day Furkot road trip with named waypoints and dates via /trip
- Add or modify stops on an existing trip identified by trip_id through `/trip/{trip_id}/stop`
- Track stops the traveller has chosen to skip using `/trip/{trip_id}/skipped`
- Authenticate third-party trip integrations through OAuth 2.0 authorization-code or implicit flows
- Synchronise itinerary changes between Furkot and an external travel planner without sharing user credentials

## Use cases

### Itinerary Sync from a Travel Planner

Push a curated multi-stop itinerary from a third-party travel app into Furkot by calling /trip to create the trip and then `/trip/{trip_id}/stop` for each waypoint, so the traveller can use Furkot's mobile features for navigation, mileage, and lodging suggestions on the road. OAuth 2.0 authorization-code flow keeps user credentials in Furkot.

Example prompt: Authorise the user via OAuth, then call /trip to create a trip and `/trip/{trip_id}/stop` for each of three destinations from the user's saved list.

### RV Detour Handling

When an RV-focused companion app detects that the user has skipped a planned stop, it calls `/trip/{trip_id}/skipped` to record the skip in Furkot so the remaining itinerary recalculates correctly. Recording skipped stops keeps the Furkot trip in sync with reality without rebuilding the route from scratch.

Example prompt: Call `/trip/{trip_id}/skipped` with the stop the traveller bypassed and return the updated trip state.

### Trip Backup and Versioning

Back up Furkot itineraries into a separate storage system by periodically pulling each user's trips and stop lists through the OAuth-authorised endpoints, then storing the snapshots for restore-on-demand. This keeps trip plans recoverable even if the user accidentally deletes a stop.

Example prompt: Pull the current trip state via /trip and the stop list via `/trip/{trip_id}/stop` and store both as a JSON snapshot.

### Agent-Managed Trip Updates via Jentic

An AI travel-planning agent receives natural-language requests like 'add Yellowstone to my Tuesday trip' and uses Jentic to discover the right Furkot operation, load its schema, and execute the call against the user's authorised account. Jentic handles the OAuth token isolation so the agent never touches the user's credentials.

Example prompt: Search Jentic for 'add a stop to a furkot trip', load `/trip/{trip_id}/stop`, and execute it for trip_id 12345 with the new waypoint.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/trip` | Create or update a Furkot trip |
| POST | `/trip/{trip_id}/stop` | Add or update a stop on a trip |
| POST | `/trip/{trip_id}/skipped` | Record stops the traveller has skipped |

## Key resources

- **Trip** — Create and update Furkot multi-day road trips via the /trip endpoint.
- **Stop** — Manage ordered waypoints on an existing trip via `/trip/{trip_id}/stop.`
- **Skipped** — Record skipped stops on a trip via `/trip/{trip_id}/skipped.`

## Why Jentic

- **Setup:** Wiring Furkot Trips by hand means running its OAuth 2.0 authorization-code flow against trips.furkot.com, managing token exchange and the read:trips scope, and refreshing tokens yourself. Through Jentic you install once, import Furkot Trips from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Furkot puts the trip id in the URL path (`/trip/{trip_id}/stop`), so a rule can pin your agent to one trip: it can add stops and skipped stops for that trip and nothing else. You choose the operations it may call, so creating new trips is not included unless you add it.
- **Credential handling:** Your Furkot OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Furkot trip' or 'add a stop to a trip', and Jentic returns the matching Furkot operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **GraphHopper Directions API** — Routing and turn-by-turn directions API that can supply navigation overlays for Furkot trips.
- **Route4Me API** — Multi-stop route optimisation API used as an alternative when fleet-style optimisation matters more than trip planning.

## FAQ

### What authentication does the Furkot Trips API use?

Furkot Trips uses OAuth 2.0 with both authorization-code and implicit flows defined in the spec under furkot_auth_access_code and furkot_auth_implicit. Through Jentic, the access token is held in the encrypted vault and injected at request time so the agent never sees it.

### Can I add stops to an existing Furkot trip with this API?

Yes. Send the new stop payload to `/trip/{trip_id}/stop` with a valid OAuth bearer token; the response returns the updated stop list so you can confirm ordering and persistence on your side.

### What are the rate limits for the Furkot Trips API?

The OpenAPI spec does not declare rate limits for /trip, `/trip/{trip_id}/stop`, or `/trip/{trip_id}/skipped`, and Furkot does not publish numeric quotas at help.furkot.com. Treat the API as best-effort and back off on HTTP 429 responses.

### How do I sync a road trip into Furkot through Jentic?

Authorise the user with the Furkot OAuth flow, run a Jentic search for 'create a furkot trip', load /trip, and execute it with your itinerary payload, then call `/trip/{trip_id}/stop` for each waypoint. Get started with Jentic One, the self-hosted execution layer.

### Does the API let me delete a stop from a trip?

The spec exposes only /trip, `/trip/{trip_id}/stop`, and `/trip/{trip_id}/skipped` operations; outright deletion is not part of the published surface, but the skipped endpoint can mark a stop as bypassed during the trip.

### Can I limit what my agent is allowed to do with the Furkot Trips API?

Yes. Because you run Jentic One yourself, your own rules decide which Furkot operations the agent may call, so you can allow adding stops through `/trip/{trip_id}/stop` and recording skips through `/trip/{trip_id}/skipped` while withholding trip creation via /trip. Since Furkot puts the trip id in the URL path, a rule can pin the agent to a single trip id, letting it edit only that itinerary and nothing else. Your Furkot OAuth token is held by your instance and injected at request time, so the agent never sees the credential.