Potniq field guide
Your assistant supplies the intent. Potniq stores the itinerary, connects the stops and calculates when to leave. Start with the web app, or explore the MCP developer preview.
Workflow version: 2026-10-05
Call get_connection_status first. If it answers, the connection is live: confirm email_hint matches the traveler before writing or forwarding. If write_access is unavailable, write access is not offered by this Potniq connection right now. Do not ask the traveler to reconnect; report it and stop before pasted trip writes. Verified email forwarding can proceed with read access. For pasted trip writes, proceed if write_access is granted; if pending_user_action is approve_write_access, ask the traveler to reconnect from their host and approve write access on the Potniq consent screen. If after one reconnect the status is still read-only, ask the traveler to disconnect the client at https://potniq.com/connections and reconnect so a fresh consent screen requests write access. If that still fails, stop and report. Never approve consent for them. If disconnected, add the MCP server URL in the host remote MCP settings (Streamable HTTP with OAuth). Make at most one reconnect attempt, then stop and report.
Booking email import availability depends on the account rollout. If import is available, review the extracted details before adding them to a trip. An assistant can create structured travel items from details you provide, or submit pasted confirmation text with submit_booking_text to save a draft for review; drafts do not become trips automatically. Agents signing a traveler up or importing bookings should follow the agent start guide.
MCP · Developer preview
Use a host that supports remote MCP over Streamable HTTP and OAuth. Add the server URL in its MCP connection settings, then follow the browser sign-in and Potniq consent flow.
https://api.potniq.com/mcpget_connection_status first and confirm the account with the traveler. With the required permission, ask: “What trips do I have coming up?” If you have no trips, create one in the web app or request write access and supply the travel details.Preview status: the URL is the documented server address, not a guarantee of access from every host. Live OAuth and host compatibility are still being validated. No assistant is listed as tested here. Hosts with unsupported callbacks or account restrictions may be unable to connect; use the web app while setup is unavailable.
“Are any of my saved departures due?”
Read permission. Turn on Saved departure reminders in the web app for each trip first, then ask the assistant to call list_departure_reminders. It checks the inbox on this interaction; it cannot wake the assistant.
“Check my next trip for timing conflicts and missing details.”
Read permission. Find the trip, then call analyze_itinerary with its ID. This checks saved facts, not live travel status.
“Export my London trip as a calendar file.”
Read permission. Use export_itinerary_calendar with the explicit trip ID; import the returned .ics snapshot manually and review omission warnings.
“What trips do I have coming up? Show me the first one.”
Read permission. Uses list_itineraries and get_itinerary.
“Create a trip with these flight, hotel and meeting details.”
Write permission. Supply exact dates, locations and local time zones; clarify missing facts first.
“Move the meeting in my London trip to 10:30 on 12 October 2026, London time. Keep the venue.”
Write permission. Read the existing leg, preserve its details and pass both revision timestamps unchanged. If a newer change conflicts, reread and rebuild the edit before retrying.
“Find London Bridge station before adding it to my trip.”
Read permission and configured place search. Choose among ambiguous results before writing.
For a new trip, call create_itinerary with a fresh UUID key and the confirmed travel facts:
{
"idempotency_key": "2d9dd7b3-53e7-4c3e-80f8-63c45f5617d2",
"title": "London client visit",
"legs": [
{
"type": "activity",
"leg_data": {
"activity_name": "Client meeting",
"location": {
"address": "QEII Centre, Broad Sanctuary, London SW1P 3EE, UK"
},
"start_time": {
"timestamp": "2026-10-12T09:00:00+01:00",
"timezone": {
"timezoneId": "Europe/London"
}
},
"end_time": {
"timestamp": "2026-10-12T11:00:00+01:00",
"timezone": {
"timezoneId": "Europe/London"
}
},
"booking_reference": "MEETING-EXAMPLE"
}
}
]
}To add a meeting to an existing trip, call add_leg with its trip ID and a fresh key for that operation:
{
"idempotency_key": "96c6d469-5b3a-4e87-b4d4-bd14854f40c7",
"itinerary_id": "f10b92d5-3a8c-4ed3-94c9-b94c5a3b0a11",
"type": "activity",
"leg_data": {
"activity_name": "Client meeting",
"location": {
"address": "QEII Centre, Broad Sanctuary, London SW1P 3EE, UK"
},
"start_time": {
"timestamp": "2026-10-12T09:00:00+01:00",
"timezone": {
"timezoneId": "Europe/London"
}
},
"end_time": {
"timestamp": "2026-10-12T11:00:00+01:00",
"timezone": {
"timezoneId": "Europe/London"
}
},
"booking_reference": "MEETING-EXAMPLE"
}
}Retain each key and its exact input. After a timeout, resend the same request with the same key. A replay identifies the original save; read get_itinerary for current details.
First call get_itinerary with the chosen trip ID. This illustrative response excerpt contains the trip revision and the meeting's own revision:
{
"id": "f10b92d5-3a8c-4ed3-94c9-b94c5a3b0a11",
"title": "London trip",
"updated_at": "2026-09-30T12:00:00.123456+00:00",
"legs": [
{
"id": "6c9b0e61-6475-4fd1-9b09-d81073517940",
"type": "activity",
"order_index": 1,
"updated_at": "2026-09-30T11:59:00.654321+00:00",
"leg_data": {
"activity_name": "Client meeting",
"location": {
"address": "QEII Centre, Broad Sanctuary, London SW1P 3EE, UK"
},
"start_time": {
"timestamp": "2026-10-12T09:00:00+01:00",
"timezone": {
"timezoneId": "Europe/London"
}
},
"end_time": {
"timestamp": "2026-10-12T11:00:00+01:00",
"timezone": {
"timezoneId": "Europe/London"
}
},
"booking_reference": "MEETING-EXAMPLE"
}
}
]
}After confirming the date and London local time, call update_leg with the complete editable meeting details. Preserve the venue, end time and booking reference. Copy both updated_at strings unchanged into the top-level precondition fields:
{
"itinerary_id": "f10b92d5-3a8c-4ed3-94c9-b94c5a3b0a11",
"leg_id": "6c9b0e61-6475-4fd1-9b09-d81073517940",
"expected_updated_at": "2026-09-30T12:00:00.123456+00:00",
"expected_leg_updated_at": "2026-09-30T11:59:00.654321+00:00",
"type": "activity",
"leg_data": {
"activity_name": "Client meeting",
"location": {
"address": "QEII Centre, Broad Sanctuary, London SW1P 3EE, UK"
},
"start_time": {
"timestamp": "2026-10-12T10:30:00+01:00",
"timezone": {
"timezoneId": "Europe/London"
}
},
"end_time": {
"timestamp": "2026-10-12T11:00:00+01:00",
"timezone": {
"timezoneId": "Europe/London"
}
},
"booking_reference": "MEETING-EXAMPLE"
}
}Recalculate and review: a successful edit returns processing: "pending". Potniq recalculates the affected transit in the background. Call get_itinerary again and present new leave-by times only once transit_status is ready; failed means a route did not calculate.
On REVISION_CONFLICT: the stale edit was rejected. Read the trip again, compare the latest meeting with your intended change and preserve unrelated updates. If the meeting's relevant details changed, ask the traveler how to proceed. Rebuild the edit from the latest facts and copy their revisions unchanged. Never just replace the revision timestamps on an old payload, and never replay a stale edit automatically.
For update_itinerary, supply only the trip revision as expected_updated_at alongside the trip ID and new title. These preconditions are required; background updates can make them stale. After a timeout, reread first to see whether the requested change already landed before deciding to retry.
Potniq generates transit between consecutive stops and works back from when you need to arrive. Driving uses Google routing with traffic forecasts for the planned departure time. Public transit and walking are calculated where they are viable; walking is offered only for short distances.
Buffers are added on top: by default you arrive at the airport 2 hours before a flight departs, and you can change this per flight. Ground transport bookings have their own default arrival buffers.
These are estimates calculated when the trip is saved or changed, not live monitoring. Potniq does not track flights or traffic in the background, send alerts or guarantee arrival. Check actual conditions before you set off.
Open a saved itinerary and select Download calendar (.ics), then import the file into your calendar app. Save or discard any edits first. An approved read connection can also request export_itinerary_calendar with the trip ID.
This is a snapshot, not a subscription or automatic sync. After changing a trip, export it again and review your calendar for duplicate entries. Transit entries are estimates; pending routes and items with invalid dates are omitted with warnings.
The file contains travel locations and schedule details. Anyone you share the file or imported calendar with may see them. Review the destination calendar's visibility before importing. Offline downloads use your cached saved trip.
On a saved itinerary, turn on Saved departure reminders to show a reminder in the trip and to assistants you’ve connected with read permission. The setting starts off for every trip. Save your changes before turning it on; you can turn it off while editing whenever you are online.
The window is fixed at 15 minutes before a saved departure. Each reminder expires at departure. Only completed Google Maps route calculations qualify; incomplete routes and saved timing conflicts can prevent reminders from appearing. The panel checks while visible and on return to the page, and clears reminder details offline.
An assistant retrieves the inbox with list_departure_reminders when you interact with it. This does not send email, browser push or other notifications, wake assistants, or check live traffic and flight status. Turning a setting off removes current reminders from future reads; information already received by an assistant follows that host’s policies.
Tools require an authenticated, active account and an approved connection. Your host discovers the full input schemas from the server. This guide describes the current contracts.
Inspect owned forwarded deliveries and unconfirmed drafts. Repeat the same since window from page one to discover late-bound deliveries; reread known IDs for processing changes. Missing deliveries are not proof of success.
Recover saved delivery or draft facts and outcomes, including dismissed drafts. Available sender, subject and message-ID headers are retained for new shared deliveries; legacy rows and missing headers remain null. Draft-level duplicate/change/cancellation classification is conservative and a hint only; a null classification (older drafts) is unresolved. Partial or unresolved facts need review. Poll a submitted delivery with bounded backoff until imported, duplicate, failed, unsupported or needs_information.
Submit bounded pasted confirmation text and optional label to the durable draft pipeline. Use one UUID retry key per source; changed input with that key conflicts. Inspect the returned delivery with get_import.
Exclude a pending draft with a durable outcome. Retries are safe; confirmed drafts and trips are not changed.
Call first to check the active account, masked email_hint, registered client, approved grant and currently available tools. Confirm the intended traveler before writing. When write access is offered, a read-only grant returns pending_user_action: approve_write_access for trip writes. Verified email forwarding can proceed with read access.
Check flag-gated forwarding availability, the reported shared destination and verification status for one sender_address. Unverified senders need verify_forwarding_mailbox in Profile; the traveler enters the code themselves. No other mailboxes or verification internals are returned.
Find current and upcoming trips by default. Use past or all to include history; page through longer lists.
Read a trip by ID, or select the current or next upcoming trip. Ambiguous matches return candidates to choose from. Returns the trip and leg updated_at values used to guard edits.
Return a read-only completion receipt for one trip and up to 20 supplied delivery or draft IDs: trip link, trip_state, per-source dispositions, routing status, leave-by times only when every route calculated, and unresolved items. Covers only the supplied sources; agreed_source_set_verified is always false. Source content is never returned.
Assess a trip by explicit ID using saved facts: timing conflicts, arrival buffers, incomplete routes, missing details and the next timed action. Ready means no detected stored-data issues, not a travel guarantee.
Export a saved trip by explicit ID as an iCalendar (.ics) snapshot. Includes supported dated travel items and calculated transit; invalid or unfinished items are omitted with warnings. Import it into your calendar manually. Changes do not automatically sync.
Read current saved departure reminders for trips you explicitly enabled in the web app. Optional limit defaults to 20 (maximum 50). Items use saved route estimates, appear only within 15 minutes before departure, and expire at departure. No notifications or live checks.
Resolve a location before writing. Confirm ambiguous matches and preserve Google Maps and provider attributions. Requires configured place search.
Create a trip from 1–30 ordered travel items. Include a dated item and a location that participates in transit. Supply a UUID idempotency_key and reuse it with identical input after a timeout. Potniq generates the connecting transit.
Add one travel item to an explicit trip. Supply a UUID idempotency_key and reuse it with identical input after a timeout. Potniq assigns its ID and recalculates affected transit.
Change an existing trip title using its explicit ID and required expected_updated_at from the last read.
Replace one existing user leg. Requires expected_updated_at from the trip and expected_leg_updated_at from that leg. Read first and preserve unrelated details. Generated transit cannot be edited through this tool.
Writes need explicit trip IDs where applicable. Timed items need timestamps with offsets. Potniq assigns IDs and ordering; do not submit generated transit items. For create_itinerary and add_leg, generate one UUID idempotency_key per new operation and retain it with the input. After a timeout, retry the same key and input. Results identify the original saved trip or leg; use get_itinerary for current details. Edit tools still require rereading before retrying.
Read: your approved assistant can access your itinerary details, retrieve saved departure reminders for trips you opted into, and resolve places. Trip data includes the travel locations, schedule and booking details saved in Potniq. Share access only with an assistant you trust.
Write: the assistant can create trips, add travel items and change supported existing details. Read consent does not permit writes. Upgrading requires a new approval and reconnecting to obtain a fresh token.
Disconnect: revoke the connection from the Connections page. Revocation blocks its access to Potniq; data already received by your host follows that host's policies.
Timing: calculations use routing estimates and configured buffers. They are estimates, not a guarantee. Check the actual flight, rail and local conditions before travel.
Coming later: automatic disruption monitoring, proactive leave-by alerts, booking and rebooking are not current MCP capabilities. Potniq does not autonomously purchase travel or contact providers.
Read our privacy policy for data handling and account rights.
Prefer a screen? Open your itineraries. Agents starting from scratch: see the agent start guide. For machine-readable orientation, see llms.txt.