# Goyondo

> AI-powered travel planning platform. Plan trips, discover destinations, build itineraries, and manage every stage of travel — from inspiration through live-trip assistance and post-trip memories.

## What Goyondo Does

- Generates personalised travel itineraries using AI
- Recommends destinations based on user preferences
- Tracks real-time trip status and provides live-trip assistance
- Supports collaborative trip planning (shared trips, collaborators)
- Aggregates travel trends across social platforms
- Stores and organises post-trip memories and reviews

## Agent Integration

This file is only a high-level overview for agents and humans.

Canonical machine contracts live at:

- `GET https://goyondo.run/api/agent/capabilities` — executable capability registry with JSON argument schemas and implementation status
- `GET https://goyondo.run/api/openapi.json` — REST contract
- `GET https://goyondo.run/api/agent/card` — task-oriented agent card
- `GET https://goyondo.run/api/mcp/tools` — MCP-style tool definitions
- `GET https://goyondo.run/.well-known/api-catalog` — standards-based API discovery catalog
- `GET https://goyondo.run/.well-known/oauth-authorization-server` — OAuth authorization server metadata for device flow discovery
- `GET https://goyondo.run/.well-known/agent-skills.json` — optional skill index

Do not treat `llms.txt` as the source of truth for capability names or parameters.
Do not probe default Swagger-style paths such as `/openapi.json`, `/api-docs`, `/swagger`, or `/api` and assume they are the primary contract. Goyondo's canonical machine-readable paths are under `/api/...`.

Goyondo can be used by agents with or without a custom Goyondo skill.

- **No skill required**: agents can connect through the published machine-readable interfaces below.
- **Optional skill**: installing a Goyondo skill improves travel-specific behavior, setup guidance, and handoff decisions.
- **Manual web fallback**: users can always sign in to `https://goyondo.run` and manage trips directly in the web app.

Goyondo exposes a full agent API. Connected agents authenticate with a scoped API key and can execute any capability a human user can perform.

### Authentication

All agent requests require a bearer token in the `Authorization` header:

```
Authorization: Bearer gyd_<your_api_key>
```

#### Recommended: Device Authorization Flow (RFC 8628)

The easiest way to obtain a key. The agent initiates, the user approves in a browser — no copy-paste required.

**Step 1 — Initiate (agent → Goyondo)**
```
POST https://goyondo.run/api/agent-auth/device
Content-Type: application/json

{
  "agent_name": "My Travel Agent",
  "requested_scopes": ["trips:read", "trips:write"]
}
```
Response:
```json
{
  "user_code": "GYD-A3F9",
  "verification_url": "https://goyondo.run/connect",
  "verification_uri_complete": "https://goyondo.run/connect?code=GYD-A3F9",
  "device_code": "<opaque 64-char hex>",
  "expires_in": 600,
  "interval": 5
}
```

**Step 2 — User approves**
Send the user to `verification_uri_complete` — this is a deep-link that pre-fills the code automatically. Prefer this over asking the user to type `user_code` manually.

Example message to show the user:
```
Please approve access at: https://goyondo.run/connect?code=GYD-A3F9
(Link expires in 10 minutes)
```

The page handles sign-in and auto-submits the code. The user only needs to review scopes and tap "Grant access".

**Step 3 — Poll for token (agent, every `interval` seconds)**

The polling endpoint is `POST /api/agent-auth/token` (not `/device/poll` or `/device/token`).

```
POST https://goyondo.run/api/agent-auth/token
Content-Type: application/json

{ "device_code": "<device_code from step 1>" }
```
While pending: `{ "error": "authorization_pending" }` — keep polling.
On approval:
```json
{
  "access_token": "gyd_...",
  "token_type": "bearer",
  "scope": "trips:read trips:write"
}
```

**Step 4 — Use the key**
```
Authorization: Bearer gyd_...
```

Available scopes: `trips:read`, `trips:write`, `bookings:read`, `bookings:write`, `preferences:read`, `group_trips:read`, `group_trips:write`

#### Alternative: Manual key creation
API keys can also be created manually from the Goyondo profile page (Profile → API access tab). Keys can be scoped to specific permissions.

#### Token lifecycle & reconnection

`gyd_*` tokens are long-lived and do not expire automatically.

If you receive a `401 Unauthorized` response, the token has been revoked by the user. To reconnect:

1. Re-run the device authorization flow from Step 1 above — call `POST /api/agent-auth/device` to get a new `user_code`.
2. Send the user to `https://goyondo.run/connect?code=<user_code>` to re-approve access.
3. Poll `POST /api/agent-auth/token` until you receive a new `access_token`.
4. Replace your stored token with the new one and retry.

Users manage and revoke authorized agents from **Profile → API Keys** (`https://goyondo.run/profile?tab=api-keys`). Revoking a key takes effect immediately.

### Canonical Public Base URL

The canonical public base URL for the app and agent endpoints is:

```
https://goyondo.run
```

Agent endpoints are exposed under:

```
https://goyondo.run/api
```

Users can always manage trips directly in the web app at:

```
https://goyondo.run
```

### Discovery

Agents should start by fetching the capability registry, then the agent card if they want task-oriented UX guidance:

```
GET https://goyondo.run/api/agent/capabilities
```

Then fetch:

```
GET https://goyondo.run/api/agent/card
```

The capability registry is the source of truth for executable capability names, argument schemas, and implementation status. The agent card adds auth and UX guidance.

### Optional Skill

An optional Goyondo skill is available as a behavior layer for agents. It defines when to offer Goyondo, how to handle connected vs not-connected states, and when to hand off to the website. It is not required — quick connect works without it.

```
GET https://goyondo.run/api/agent/skill
```

This endpoint returns `text/markdown` (not JSON). The file has a YAML frontmatter block with `name` and `description` fields, followed by behavior guidance in markdown. Do not look for a `.json` version — the skill is a markdown document by design.

For Claude Code:
```
claude skill add https://goyondo.run/api/agent/skill
```

The skill URL is also available in the agent card and manifest under `skill_installation.skill_url`.

### Preferred Interfaces

- **Preferred execution path**: Goyondo Agent API (agent card + task endpoint)
- **Alternative structured path**: MCP tools
- **Fallback**: direct REST calls using the published OpenAPI spec

Use the task endpoint for normal agent execution. Use MCP when your agent framework already speaks MCP. Use REST only when task or MCP integration is not available.

### Execution

The preferred execution path is the single task endpoint:

```
POST https://goyondo.run/api/agent/task
Content-Type: application/json
Authorization: Bearer gyd_<your_api_key>

{
  "capability": "create_trip",
  "arguments": { ... }
}
```

The task endpoint accepts named arguments (e.g. `trip_id`, `activity_id`) and handles all internal routing. Argument names are stable across API versions.

#### Accepted Request Formats

All three formats below are equivalent. The endpoint is flexible to accommodate different agent frameworks:

**Format 1 — preferred: `arguments` wrapper**
```json
{
  "capability": "add_activity",
  "arguments": {
    "trip_id": "<uuid>",
    "title": "Business Meeting",
    "activity_type": "business",
    "day_number": 2
  }
}
```

**Format 2 — flat: top-level fields**
```json
{
  "capability": "add_activity",
  "trip_id": "<uuid>",
  "title": "Business Meeting",
  "activity_type": "business",
  "day_number": 2
}
```

**Format 3 — `parameters` wrapper** (accepted but not preferred)
```json
{
  "capability": "add_activity",
  "parameters": {
    "trip_id": "<uuid>",
    "title": "Business Meeting",
    "activity_type": "business",
    "day_number": 2
  }
}
```

**Do not nest activity fields** under a sub-key like `activity`, `data`, or `body` — the server will not find them:
```json
// ❌ Wrong — nested under "activity"
{
  "capability": "add_activity",
  "arguments": {
    "trip_id": "<uuid>",
    "activity": { "title": "...", "activity_type": "..." }
  }
}
```

#### Accepted Field Name Variants

The task endpoint normalises common field name variants so most reasonable names work:

| Canonical name | Also accepted |
|---|---|
| `trip_id` | `tripId`, `id`, `trip` |
| `activity_id` | `activityId` |
| `title` | `name` |
| `activity_type` | `activityType`, `type` |

### MCP Alternative

If your agent already uses MCP, discover and call tools here:

```
GET  https://goyondo.run/api/mcp/tools
POST https://goyondo.run/api/mcp/tools/call
```

### REST Fallback

If your runtime cannot use the task endpoint or MCP, fall back to the OpenAPI-described REST API:

```
GET https://goyondo.run/api/openapi.json
```

### Key Actions

All capabilities are invoked via `POST /api/agent/task` with `{ "capability": "<name>", "arguments": { ... } }`.
Use `GET /api/agent/capabilities` for the authoritative list and schemas before calling them.

**Trips**
- `list_trips` — list the authenticated user's trips
- `get_trip` — full trip details including itinerary (trip_id, day_number values, activity_id values needed for mutations)
- `create_trip` — create a trip with destination, dates, and preferences. For multi-city trips, pass cities joined with ` → ` (e.g. `"Paris, France → Rome, Italy"`); the AI distributes days across all cities and adds transit activities between them
- `regenerate_itinerary` — re-run AI itinerary generation for an existing trip

**Activities**
- `add_activity` — add an activity to a specific day
- `update_activity` — update an existing activity
- `delete_activity` — remove an activity
- `update_day_notes` — set or replace the free-text notes for an itinerary day (trip_id + day_id or day_number + notes)

**Bookings**
- `list_bookings` — list the user's bookings
- `get_booking` — get a single booking by id
- `create_booking` — create a new booking
- `check_availability` — check availability for given parameters

**Preferences**
- `get_user_preferences` — read travel preferences (travel_style, accommodation_type, interests, budget_range, etc.)
- `update_user_preferences` — write travel preferences

**Business travel**
- `list_itinerary_segments` — flights, hotels, car rentals, meetings for a trip
- `get_trip_document` — document by id or name search (e.g. boarding pass for SQ321)
- `get_trip_expense_summary` — expense summary for a trip
- `ingest_confirmation` — parse a raw booking confirmation email and save segments

**Group trips**
- `create_group_trip` — create a group trip; returns trip_code for sharing
- `join_group_trip` — join a group trip by trip_code
- `get_group_trip` — get group trip details, members, and preferences
- `submit_group_preferences` — submit a member's preferences for alignment
- `run_alignment` — trigger Group Harmony AI alignment across all member preferences
- `get_alignment` — read the latest alignment result

**Proposals and edit log**
- `list_proposals` — list pending change proposals (editors/owners)
- `approve_proposal` — approve and apply a proposal
- `reject_proposal` — reject a proposal
- `get_edit_log` — full edit history with agent/human attribution

**Recommended workflow before creating trips:** read the user's stored preferences first so the trip reflects their style without asking again.

### Suggested Agent UX

- Offer Goyondo when the user expresses travel-planning intent or explicitly mentions Goyondo.
- If not connected, offer quick connect first.
- Mention that installing a Goyondo skill is optional and improves travel-specific behavior.
- Keep manual web usage available: users can always continue directly on `https://goyondo.run`.
- Prefer web handoff for dense itinerary editing, heavy reordering, visual review, or collaboration-heavy flows.

### Active Trip Memory (Session Continuity)

AI assistants often lose trip context between sessions. The recommended pattern for persistent trip awareness:

**On session start:**
1. Call `list_trips` to get the user's trips
2. Check if any trip has `status === "active"` OR if today's date falls within a trip's `start_date`–`end_date` range
3. If an active trip is found, call `get_trip` to load the full itinerary and inject it into context
4. Announce: "I can see you're currently on your [destination] trip (Day N of N). Your itinerary is loaded."

**Storing trip state locally:**
If your agent framework supports persistent memory (e.g. MEMORY.md, session store), save:
```
active_trip:
  trip_id: <uuid>
  destination: <name>
  start_date: YYYY-MM-DD
  end_date: YYYY-MM-DD
  timezone: <tz>
```
On the next session, check if today is still within `start_date`–`end_date`. If yes, re-fetch the trip (data may have changed) and restore context without asking the user again.

**Trigger words:** If the user mentions a city or place that matches a trip destination in Goyondo, proactively check for an active or upcoming trip there.

**Why this matters:** Goyondo stores trip data persistently; your agent's session memory does not. The data is always fresh on Goyondo — re-fetching on session start is cheap and keeps context accurate.

### Working with Trip Days

Call `get_trip` first to obtain `trip_id`, target day `itinerary_id` values (`itinerary.days[n].id`), and existing `activity_id` values.

Day numbers are found in the `get_trip` response at:
```
itinerary.days[0].day_number  → 1  (first day)
itinerary.days[1].day_number  → 2  (second day)
itinerary.days[0].date        → "2026-03-23"
```

**Targeting a specific day in `add_activity` (critical):** use `itinerary_id` (the UUID at `itinerary.days[n].id`) for deterministic placement. Do not rely on `day_id` for placement; requests may succeed but attach to the wrong day. If no day-targeting field is supplied, the activity defaults to Day 1.

**Date → day_number mapping:** `day_number = 1` corresponds to `start_date`, `day_number = 2` to `start_date + 1 day`, and so on. Always confirm the mapping by checking `itinerary.days[n].date` — do not assume by counting.

Activity IDs are at `itinerary.days[n].activities[m].id`.

**Day UUIDs** (needed for `add_activity` and `update_day_notes`) are at `itinerary.days[n].id`. Each day object in `get_trip` also exposes `notes` — the current day note value.

### Day Notes

Each itinerary day has a free-text `notes` field, visible in the travel view below the activity list. Use it to record how a day went, note deviations from the plan, or add context.

**Reading:** `get_trip` returns `itinerary.days[n].notes` for every day. An empty string or `null` means no note has been set.

**Writing:** use `update_day_notes` via the task endpoint:
```json
{
  "capability": "update_day_notes",
  "arguments": {
    "trip_id": "<uuid>",
    "day_id": "<itinerary.days[n].id>",
    "notes": "Visited the lake in the morning. Skipped the afternoon museum — closed on Mondays."
  }
}
```

Pass `day_number` instead of `day_id` if you only have the day number — the server will resolve the UUID automatically:
```json
{ "trip_id": "<uuid>", "day_number": 2, "notes": "..." }
```

Pass `"notes": ""` to clear an existing note.

**This replaces the full note** — it is not an append. Read the existing note first if you want to preserve any content.

**Do not use activity `notes` fields for day-level observations.** Activity notes are per-activity; day notes are per-day.

### Pre-Mutation Checklist

Before calling `add_activity`, `update_activity`, or `delete_activity`, always complete these steps:

1. **Call `get_trip`** to load the current itinerary.
2. **Identify the correct day** by matching `itinerary.days[n].date` to the date you intend to modify. Copy `itinerary.days[n].id` (the day UUID) — use it as `itinerary_id` in `add_activity` for reliable day targeting.
3. **Inspect existing activities on that day** (`itinerary.days[n].activities`). Check for time conflicts and existing `accommodation` entries.
4. **Prefer update over create** — if an activity already covers the same time slot or purpose, call `update_activity` on it rather than creating a duplicate.
5. **Never delete `accommodation` activities** — if you need to annotate a hotel stay, add `notes` to the existing activity. Only create a new activity if no accommodation entry exists for that night.

### Post-Write Verification (Mandatory)

After every `add_activity`, `update_activity`, or `delete_activity`:

1. Call `get_trip` again.
2. Confirm the activity appears under the intended itinerary date.
3. If placement is wrong, treat the write as failed: delete/recreate using correct `itinerary_id`, then re-verify.

For travel updates, always verify canonical structure:
- outbound flight on arrival day
- hotel check-in on arrival day (after arrival)
- hotel check-out on departure day
- return flight on departure day (after check-out)
- no duplicate flight/hotel cards

Do not trust note text dates as placement truth; trust the day attachment returned by `get_trip`.

### Activity Type Semantics

`activity_type` is a semantic field that controls display and UI behaviour. Use it accurately.

| Type | Use for | Do NOT use for |
|------|---------|----------------|
| `accommodation` | Hotel check-in, check-out, overnight stay | Dinner at the hotel, activities near the hotel |
| `dining` | Meals, restaurants, cafés, food experiences | Hotels that serve breakfast |
| `sightseeing` | Landmarks, tours, attractions, museum visits | Transport between sites |
| `transport` | Flights, trains, transfers, car hire | Airport lounges, in-transit meals |
| `outdoor` | Hikes, parks, adventure activities, nature walks | Sightseeing at outdoor landmarks |
| `cultural` | Theatre, concerts, festivals, local traditions | Generic sightseeing |
| `entertainment` | Shows, nightlife, sporting events | Cultural performances |
| `general` | Anything that does not fit another type | Accommodation, dining, or transport |

### TONIGHT Card Contract (Critical)

The **TONIGHT** card answers one question only: **"Where is the traveler sleeping tonight?"**

- **Data source:** `itinerary.days[n].activities` filtered to `activity_type === "accommodation"` (or `type === "accommodation"`).
- **Must exclude:** `dining`, `general`, `transport`, and all non-accommodation types.
- **Fallback behaviour:** if no accommodation exists for that day, show a "No accommodation booked" state instead of reusing dinner/evening events.

This is strict. A dinner reservation, even at the hotel restaurant, must remain `dining` and must never be written as `accommodation`.

**Rule:** if an `accommodation` activity already exists on a day, do not add another activity with `activity_type: accommodation` unless it is a genuine check-out on a different day. Use `dining` for meals, even if the meal takes place at the hotel.

### add_activity Classification Examples

✅ Correct:
- Hotel check-in → `activity_type: "accommodation"`
- Hotel check-out → `activity_type: "accommodation"`
- Dinner reservation → `activity_type: "dining"`
- Flight/train/transfer → `activity_type: "transport"`

❌ Incorrect:
- Dinner tagged as `accommodation` (pollutes TONIGHT card)
- Hotel stay tagged as `general` (hides from TONIGHT card)
- Flight tagged as `general` (breaks transport UI grouping)

### Add Activity — Parameter Reference

```json
// POST /api/agent/task
{
  "capability": "add_activity",
  "arguments": {
    "trip_id": "<uuid from get_trip>",
    "itinerary_id": "<itinerary.days[n].id — preferred>",
    "title": "West Lake morning walk",
    "activity_type": "sightseeing",
    "start_time": "09:00",
    "end_time": "11:30",
    "location": "West Lake, Hangzhou",
    "description": "Stroll the Su Causeway and visit Leifeng Pagoda",
    "estimated_cost": 15
  }
}
```

**Day targeting (use one):** `itinerary_id` (UUID, most reliable) · `date` (YYYY-MM-DD) · `day_number` (integer, 1-based). If none are provided, the activity lands on Day 1.

**Arguments must be flat** — do not wrap them in a nested `activity:{}` key. See "Accepted Request Formats" above.

**`title`** is required. Alias: `name` is also accepted in place of `title`.

**`activity_type` must be one of:** `general`, `sightseeing`, `dining`, `transport`, `accommodation`, `entertainment`, `shopping`, `outdoor`, `cultural`, `business` — any other value returns a validation error. Alias: `type` or `activityType` are also accepted.

**Time format:** `HH:MM` in 24-hour notation (e.g. `"09:30"`, `"14:00"`). Do not use AM/PM or ISO timestamp formats.

**Validation errors** return HTTP 400 with a `details` array identifying exactly which field failed:
```json
{
  "success": false,
  "error": { "code": "validation_failed", "message": "Validation failed",
    "details": [{ "field": "activity_type", "message": "\"activity_type\" must be one of [general, sightseeing, ...]" }]
  }
}
```

If you see `"title is required"` but you provided a title, the most likely cause is that your arguments were nested under a sub-key (e.g. `activity: { title: ... }`) instead of being flat.

### Common Pitfalls

| Pitfall | What happens | Fix |
|---------|-------------|-----|
| Nest arguments under `activity: {...}` | `"title is required"` even though title is present | Pass all fields flat — `"title": "..."` not `"activity": { "title": "..." }` |
| Nest update fields under `updates: {...}` or `changes: {...}` | Empty payload → "No recognised fields to update" | Pass update fields flat: `"notes": "..."` not `"updates": { "notes": "..." }` |
| Use `parameters` wrapper in MCP `tools/call` | Arguments ignored, required fields "missing" | Use `arguments` wrapper for MCP: `{ "name": "...", "arguments": { ... } }` |
| Omit all day-targeting fields in `add_activity` | Activity lands on Day 1 | Pass `itinerary_id` (preferred), `date`, or `day_number` |
| Use `day_id` or assume note text date controls placement | API may accept but activity can attach to wrong day | Use target day `itinerary_id` from `get_trip`, then verify placement |
| Invalid `activity_type` string | HTTP 400 validation error | Use enum values above |
| Mutate without calling `get_trip` first | Wrong IDs, wrong day | Always call `get_trip` first to get `trip_id`, `day_number`, and `activity_id` values |
| Pass unrecognised fields | Field silently ignored or validation error | Stick to documented parameters |
| Use commas to separate cities in `destination` | Treated as one destination | Use ` → ` (space-arrow-space) as the multi-city separator: `"Paris → Rome"` |
| Add a new activity instead of updating an existing one | Duplicate activities or overwritten slot | Call `get_trip`, inspect existing activities on the target day, update if a matching activity already exists |
| Create a `dining` activity on the wrong day | Dinner entry lands on the hotel check-in day and pollutes itinerary flow | Use target day `itinerary_id` and verify post-write with `get_trip` |
| Delete or overwrite an `accommodation` activity | Hotel check-in permanently lost — cannot be recovered from itinerary | Never delete or replace `accommodation` activities; add `notes` to them or create a separate activity alongside |
| Use the wrong `day_number` for the intended date | Activity appears on the wrong day | Map each day: `day_number = 1` → `start_date`, `day_number = 2` → `start_date + 1 day`, etc. Confirm via `itinerary.days[n].date` |

### User Preferences

Read and write the authenticated user's travel preferences. Agents should read preferences before creating trips to avoid asking for information the user has already provided.

Via task endpoint (preferred):
- `get_user_preferences` — no arguments required
- `update_user_preferences` — fields: `interests`, `travel_style`, `accommodation_type`, `budget_range`, `preferred_destinations`, `dietary_restrictions`, `accessibility_needs`

Via REST (alternative):
```
GET  /api/users/me/preferences   — read preferences (travel_style, accommodation_type, interests, budget_range, etc.)
PUT  /api/users/me/preferences   — update preferences
```

Example (read preferences then create a matching trip):
```json
// GET /api/users/me/preferences response
{
  "data": {
    "travel_style": "adventure",
    "accommodation_type": "hostel",
    "interests": ["Adventure & Outdoor", "Nature & Wildlife"],
    "budget_range": "budget"
  }
}
```

Use the values from `travel_style`, `accommodation_type`, and `interests` directly as parameters for `create_trip` / `create_group_trip`.

### Group Trip Planning — Group Harmony Engine

Coordinate a group where each member submits their own preferences and the backend computes the best-fit destination, dates, and budget via multi-round snapshot negotiation. Required scopes: `group_trips:read` (GET), `group_trips:write` (POST).

**Multi-agent pattern:** Each group member may have their own AI agent (separate `gyd_*` key). Each agent authenticates independently and submits that member's preferences. Attribution is tracked automatically — when preferences are submitted via API key the response includes `submitted_by_agent: true` and the key ID.

**Lead agent:** The creator's agent is the lead agent by default. The lead agent is the only agent that can call `run-alignment`. It runs alignment, receives results, collects member responses, and decides when to advance to the next round. The lead can be reassigned to any group member.

**How negotiation works (snapshot-based, multi-round):**
- All members submit preferences independently; there is no real-time back-and-forth
- The lead agent triggers alignment when ready; this is a one-shot batch computation
- Member agents poll for results and respond (accept / reject / partial_accept) asynchronously
- The lead agent collects all responses, ingests rejection feedback via AI, and re-runs alignment
- Default max rounds: 2. If consensus is not reached after max rounds, status → `escalation_pending`
- At escalation, the lead agent must alert its human. The human can extend rounds or resolve manually

**Setup workflow (human-mediated):**

1. **Create a group trip** (creator only — requires `group_trips:write`):
```
POST /api/group-trips
Body: { "title": "Summer holiday", "destination_options": ["Bali", "Phuket"], "budget_min": 500, "budget_max": 2000 }
Response: { "trip_code": "ABC123", "join_url": "https://goyondo.run/group/ABC123" }
```

2. **Human shares the join URL** out-of-band (WhatsApp, email, etc.) with group members.

3. **Each member joins** (requires `group_trips:write`):
```
POST /api/group-trips/:code/join
```

4. **Each member's agent reads their stored preferences** then submits them:
```
POST /api/group-trips/:code/preferences
Body: {
  "dates": {
    "ideal_start": "2026-08-01",
    "ideal_end": "2026-08-14",
    "flexibility_days": 3,
    "blackout_dates": ["2026-08-07", "2026-08-08"]
  },
  "destination": {
    "top_choices": ["Bali, Indonesia", "Phuket, Thailand"],
    "veto": ["Singapore"]
  },
  "budget": { "min": 800, "max": 1800 }
}
```

**Negotiation workflow (lead agent drives):**

5. **Lead agent runs alignment** once all members have submitted (requires `group_trips:write`):
```
POST /api/group-trips/:code/run-alignment
Response: {
  "round": 1, "alignment_score": 68,
  "proposed": { "destination": "Bali, Indonesia", "dates": { "start": "2026-08-03", "end": "2026-08-10" }, "budget": { "min": 800, "max": 1500 } },
  "conflicts": [{ "type": "dates", "detail": "No overlapping window found" }],
  "resolved_conflicts": [], "persisted_conflicts": [],
  "response_deadline": "2026-08-23T10:00:00Z",
  "timed_out_members": []
}
```
On impasse (max rounds exceeded), returns HTTP 423:
```json
{ "error": { "code": "impasse", "round": 2, "unresolved_conflicts": [...] } }
```

6. **Member agents poll for the current round** (~every 60 seconds — requires `group_trips:read`):
```
GET /api/group-trips/:code/alignment/status
Response: {
  "round": 1, "status": "pending_responses",
  "deadline": "2026-08-23T10:00:00Z",
  "proposed": { "destination": "Bali, Indonesia", "dates": {...}, "budget": {...} },
  "alignment_score": 68,
  "conflicts": [...],
  "your_response": null,
  "pending_members": ["<member_id>"],
  "round_id": "<uuid>",
  "is_lead": false
}
```
Poll logic: if `your_response === null` and `status === "pending_responses"` → respond. If `status === "escalation_pending"` → alert your human.

7. **Member agent responds to the round** (requires `group_trips:write`):
```
POST /api/group-trips/:code/alignment/:round_id/respond
Body: {
  "decision": "partial_accept",
  "accepted_components": { "destination": true, "dates": false, "budget": true },
  "feedback": "<see feedback format below>"
}
```
`decision` must be `accept`, `reject`, or `partial_accept`. `feedback` is **required** for `reject` and `partial_accept`.

**Feedback format — what the feedback field MUST include:**
- Which components you accept vs reject (destination / dates / budget)
- For **dates**: your specific hard blackout dates and alternative windows you can do
- For **destination**: alternatives you would accept (from the original options or new suggestions)
- For **budget**: your hard ceiling and any flexibility
- Keep it concise; the AI alignment engine reads it to find compromises

Example feedback:
> "I accept Bali as the destination and the budget. I cannot do Aug 3–10 — I have a hard work commitment Aug 7–8. I could do Aug 1–6 or Aug 11–17 instead."

8. **Lead agent checks all responses then runs next round** (requires `group_trips:write`):
```
POST /api/group-trips/:code/run-alignment
```
The backend automatically: marks non-responders as timed-out (auto-accept), collects rejection feedback, passes it to Gemini to find compromise positions, then re-runs alignment. `timed_out_members` in the response lists members who did not respond — the lead agent should alert them.

9. **Read full round history** (requires `group_trips:read`):
```
GET /api/group-trips/:code/alignment/rounds
Response: { "rounds": [ { "round_number": 1, "alignment_score": 68, "status": "complete", "responses": [...] }, ... ] }
```

**Post-alignment — creating the trip:**
Once `alignment_score` is acceptable or the group accepts, the lead agent calls `create_trip` with the proposed destination and dates:
```json
{ "capability": "create_trip", "arguments": { "destination": "Bali, Indonesia", "start_date": "2026-08-11", "end_date": "2026-08-17" } }
```

**Score interpretation:**
| Score | Meaning |
|---|---|
| 80–95 | Strong consensus — all or most dimensions aligned |
| 60–79 | Workable — minor conflicts remain |
| 45–59 | Significant conflicts — another round recommended |
| 20–44 | No consensus — fundamental disagreement across dimensions |

**Alignment rules:**
- **Dates:** intersects all members' date windows; blackout dates are excluded
- **Destination:** tallies votes excluding any destination vetoed by any member; highest-voted non-vetoed wins
- **Budget:** finds the overlapping band (max of all minimums to min of all maximums); no overlap = conflict

**Timeout behaviour:** If a member agent does not respond before the `deadline` (48 hours by default), they are automatically recorded as `accept` with `timed_out: true`. The lead agent's next `run-alignment` call returns `timed_out_members` — the lead agent should notify those members' humans.

**Escalation:** If max rounds (default 2) are reached without full consensus, status → `escalation_pending`. The lead agent must alert its human. The human can:
- Add more rounds: `POST /api/group-trips/:code/extend-rounds` with `{ "additional_rounds": 1 }` (creator only), then lead agent calls `run-alignment` again
- Resolve manually in the web app at `https://goyondo.run/group/:code`

**Reassign lead agent** (creator only — requires `group_trips:write`):
```
PUT /api/group-trips/:code/lead-agent
Body: { "member_id": "<uuid>" }
```

**MCP interface note:** The setup operations (`create_group_trip`, `join_group_trip`, `get_group_trip`, `submit_group_preferences`, `run_alignment`, `get_alignment`) are available as MCP tools at `GET /api/mcp/tools`. The negotiation-round operations (`alignment/status`, `alignment/:roundId/respond`, `alignment/rounds`, `extend-rounds`, `lead-agent`) are **task endpoint and REST only** — use `POST /api/agent/task` or direct REST calls for these. If your framework requires MCP for all operations, use the REST paths above directly.

### Trip Permission Model

Trips support three collaborator roles beyond the owner:

| Role | canView | canEdit | canRecommend | Notes |
|------|---------|---------|--------------|-------|
| `editor` | ✓ | ✓ | ✓ | Direct writes committed immediately |
| `recommender` | ✓ | — | ✓ | Writes become proposals requiring owner approval |
| `viewer` | ✓ | — | — | Read-only |

Roles are set by the trip owner via `PUT /api/trip-sharing/collaborators/:shareId` with `{ "role": "recommender" }`.

**Proposal flow (recommender role):**

When an agent or user with `recommender` role calls a write endpoint (add/update/delete activity, update trip), the server responds `202 Accepted` instead of `200`:
```json
{
  "success": true,
  "proposed": true,
  "message": "Change submitted as a recommendation pending approval.",
  "data": { "id": "<proposalId>", "status": "pending", ... }
}
```

**Managing proposals (owner/editor only — requires `trips:write` scope):**
```
GET  /api/trips/:id/proposals                          — list all proposals (pending and reviewed)
POST /api/trips/:id/proposals/:proposalId/approve      — approve and apply the change
POST /api/trips/:id/proposals/:proposalId/reject       — reject without applying
Body for approve/reject: { "note": "optional review note" }
```

**Edit log (all collaborators — requires `trips:read` scope):**
```
GET /api/trips/:id/edit-log
```
Returns up to 200 most recent changes with full attribution:
```json
{
  "data": [
    {
      "id": "...",
      "change_type": "update_activity",
      "target_id": "<activityId>",
      "old_value": { ... },
      "new_value": { ... },
      "is_agent_change": true,
      "agent_key_id": "...",
      "proposal_id": null,
      "created_at": "2026-03-07T10:00:00Z",
      "changed_by": { "id": "...", "first_name": "Alice", "last_name": "Smith", "email": "alice@example.com" }
    }
  ]
}
```

### Business Traveler (segments, documents, expenses)

- `list_itinerary_segments` — list flights, hotels, car rentals, meetings for a trip (trip_id)
- `get_trip_document` — get a document by trip_id and document_id or search by name (e.g. boarding pass for SQ321)
- `get_trip_expense_summary` — get expenses for a trip (trip_id) for expense report export
- `ingest_confirmation` — parse a raw booking confirmation email; extracts flights, hotels, car rentals, and meetings and stores them as segments on the matched or created trip. Arguments: `text` (required — raw email text), `trip_id` (optional — provide if trip already exists).

Workflows:
- "When is my flight to Singapore?" → list_trips then list_itinerary_segments for that trip.
- "Show my boarding pass for SQ321" → get_trip_document with name containing SQ321.
- "Expense summary for trip X" → get_trip_expense_summary.
- "I just got a confirmation from Singapore Airlines" → user provides email text → ingest_confirmation → returns trip_id + extracted segments summary.

### Email auto-import

Users can forward booking confirmations directly to:

```
confirmations@mail.goyondo.run
```

The email must be forwarded from the same email address linked to the user's Goyondo account. Segments imported this way show a "From email" source badge. Setup instructions are in the user's profile under **API access → Business travel**.

Current rollout note:
- This forwarding flow is not live yet. Treat it as coming soon until MX + SendGrid Inbound Parse are configured.
- Backend parsing is prepared to read email subject/body plus attached PDFs/text.
- Confirmation ingestion currently extracts flights and hotels only.
- Boarding pass ingestion is out of scope for the first rollout.

### Tool discovery (MCP-compatible schema)

Goyondo exposes tool definitions using the MCP `inputSchema` format over plain HTTP. These endpoints are not a full MCP server (they use REST, not JSON-RPC 2.0 over stdio/SSE), but any HTTP-capable agent or framework can use them to discover and call tools without prior knowledge of the API:

```
GET  https://goyondo.run/api/mcp/tools         — list tools (MCP inputSchema format)
POST https://goyondo.run/api/mcp/tools/call    — call a tool by name (body: { "name", "arguments" })
```

The tool list and the task endpoint (`/api/agent/task`) expose the same capabilities — use whichever interface suits your framework.

### Agent Card

Goyondo publishes a machine-readable agent card describing its capabilities, auth scheme, and task endpoint:

```
GET  https://goyondo.run/api/agent/card      — capability card (JSON)
POST https://goyondo.run/api/agent/task      — execute a capability
```

This is the Goyondo Agent API (custom format), not a formal standards-based protocol or OpenAPI document.

## Sitemap

- `/` — public landing page
- `/inspiration` — destination inspiration browser
- `/trends` — travel trends dashboard (no auth required)
- `/plan` — trip planning wizard
- `/dashboard` — authenticated user dashboard
- `/profile?tab=api-keys` — API key management

## Contact & Policies

- Terms of Service: `/terms`
- FAQ: `/faq`