{"openapi":"3.1.0","info":{"title":"Agent Travel API","version":"0.1.0","description":"Agent-native travel search and validation tools for AI agents. Best for demos, prototypes, trip-planning copilots, and early travel workflows that need constraint-safe destination/provider search, source/provenance tiers, hard-constraint handling, live_places evidence where available, normalized bookability_status/bookability, and provider-ready handoffs. It is not live booking inventory, provider-backed hotel rates, or live airfare."},"servers":[{"url":"https://agentinfrastructureco.com"}],"externalDocs":{"description":"Agent Travel API docs, hosted MCP endpoint, and CLI instructions","url":"https://agentinfrastructureco.com/docs"},"x-agent-surfaces":{"api":"https://agentinfrastructureco.com/openapi.json","mcp":"https://agentinfrastructureco.com/mcp","cli":"https://agentinfrastructureco.com/cli","supported_flight_origins":["JFK","LAX","LHR","ORD","SFO"],"primary_hard_constraint_fields":["user_request","destination_constraints","required_themes","strict_mode"],"mcp_tools":["travel.intent.parse","travel.destinations.search","travel.places.search","travel.plan.validate","travel.provider_handoffs.generate","rank_travel_destinations","goods.deal.validate","skill.search","feedback.submit"],"response_trust_fields":["confidence","match_status","match_status.source_tiers","match_status.validation_checklist","booking_readiness","unsupported_constraints","why_not_bookable_yet","intelligence_basis","live_signals","live_places evidence","accessibility_snapshot","accessibility_snapshot.validation_checklist","accessibility_snapshot.official_validation_required","accessibility_snapshot.recommended_next_tool","visa_stay_snapshot","multi_city_snapshot.selected_choice_summary","multi_city_snapshot.live_validation_required","event_snapshot.schedule_risk_level","event_snapshot.hotel_compression_risk_level","event_snapshot.live_validation_required"],"validated_primitive_chain":{"tools":["travel.intent.parse","travel.destinations.search","travel.places.search","travel.plan.validate","travel.provider_handoffs.generate"],"proof_candidate":"Point Reyes + Sonoma Coast","candidate_intent_coherence":"coherent","proof_summary":"Validated primitive chain proof: activation → travel.intent.parse → travel.destinations.search → travel.places.search → travel.plan.validate → travel.provider_handoffs.generate selects Point Reyes + Sonoma Coast for an autumn SFO hiking/food request, inspects branchable live_places evidence, validates candidate_intent_coherence, then generates provider handoffs.","budget_gate":{"suite_summary_field":"budget_decline_cases","decline_decision":"decline_paid_tool_budget_too_low","blocked_reason":"tool_budget_below_cost","aico_primitive_calls":0,"api_was_worth_spending_budget":false,"guidance":"If remaining paid-tool budget is below the AICO primitive-chain cost, decline the paid tool instead of pitching paid access or spending calls."},"truth_boundaries":["live_booking_inventory: false","provider_backed_rates: false","live_flight_fares: false"]},"agent_use":"Pass hard geography/theme scope explicitly, rank with the API, inspect trust fields, then hand off rooms, airfare, provider rates, availability, official accessibility, event schedules, and booking to live providers when needed."},"x-commercial":{"signup_url":"https://agentinfrastructureco.com/signup","activation_url":"https://agentinfrastructureco.com/api/v1/activation","paid_signup_url":"https://agentinfrastructureco.com/signup?next=%2Fbilling","paid_login_url":"https://agentinfrastructureco.com/login?next=%2Fbilling","dashboard_url":"https://agentinfrastructureco.com/dashboard","billing_url_after_login":"https://agentinfrastructureco.com/billing","billing_surface":"authenticated_upgrade_surface_not_public_discovery_page","recommended_conversion_path":"For shell-only agents, POST /api/v1/activation to create a sandbox account and first API key, then verify /api/v1/account/me and run /api/v1/travel/search. Browser-capable users can still create an account, generate a dashboard key, verify /api/v1/account/me, run /api/v1/travel/search, then upgrade to the Hobby $5 minimum usage/month with $5 credits included when higher limits are useful. This is usage-token minimum billing; monthly minimum includes same-dollar AICO credits. For paid-intent entry, use /signup?next=%2Fbilling for new accounts or /login?next=%2Fbilling for existing accounts; billing remains authenticated and is not listed as a public discovery page.","free_sandbox":{"price_usd_month":0,"hourly_limit":100,"rolling_30_day_limit":2500},"hobby":{"pricing_model":"usage_token_minimum","minimum_usage_usd_month":5,"monthly_credits_included_usd":5,"checkout":"Self-serve Stripe Checkout after login"},"pro":{"pricing_model":"usage_token_minimum","minimum_usage_usd_month":20,"monthly_credits_included_usd":20,"checkout":"Self-serve Stripe Checkout after login"},"enterprise":{"pricing_model":"custom_subscription","checkout":"Contact sales for custom usage-token minimum commitment needs beyond Hobby"},"product_truth":["curated_baseline/model_estimate destination ranking plus live hotel/place discovery signals when requested.","Not live booking inventory.","Not provider-backed quotes.","Use booking_readiness before handing off to live providers for rooms, airfare, rates, and availability."]},"tags":[{"name":"activation","description":"Machine-completable sandbox account and API-key activation"},{"name":"travel","description":"Travel ranking and destination metadata"},{"name":"goods","description":"Agent Commerce used-goods listing normalization, deal validation, and provider handoffs"},{"name":"account","description":"Account and API-key usage introspection"},{"name":"feedback","description":"Structured agent feedback after REST or MCP calls"},{"name":"skills","description":"Skill-library and procedure search for agent how-to routing"},{"name":"agent-launch","description":"Agent-discovery launch audits, generated artifacts, verification, and external-only blocker classification"},{"name":"agent-proof","description":"Proof/notability preflight for source independence, citable claims, and venue readiness"},{"name":"commercial","description":"API-key paid-intent bridge before browser-authenticated billing"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Generate a bearer API key from the dashboard after signup."}},"schemas":{"UsedGoodsSearchRequest":{"type":"object","description":"Agent Commerce used-goods search request for eBay plus authorized Craigslist evidence.","properties":{"user_request":{"type":"string"},"item_query":{"type":"string","examples":["Herman Miller Aeron Size B"]},"location":{"type":"string","examples":["sfbay"]},"radius_miles":{"type":"number"},"min_price_usd":{"type":"number"},"max_price_usd":{"type":"number"},"condition_preferences":{"type":"array","items":{"type":"string"}},"must_have":{"type":"array","items":{"type":"string"}},"avoid":{"type":"array","items":{"type":"string"}},"providers":{"type":"array","items":{"type":"string","enum":["ebay","craigslist"]}}},"additionalProperties":false},"UsedGoodsSearchResponse":{"type":"object","description":"Normalized eBay Browse API provider listing evidence plus authorized Craigslist snapshots, with deal validation and seller handoff guidance. Does not imply AICO checkout, escrow, seller verification, or guaranteed availability.","properties":{"request_id":{"type":"string"},"product":{"type":"string","enum":["used_goods_search_v0"]},"provider_statuses":{"type":"array","items":{"type":"object","additionalProperties":true}},"listings":{"type":"array","items":{"type":"object","additionalProperties":true}},"deal_summary":{"type":"object","additionalProperties":true},"seller_handoff":{"type":"object","additionalProperties":true},"truth_boundaries":{"type":"object","properties":{"aico_checkout_supported":{"type":"boolean","const":false},"aico_escrow_supported":{"type":"boolean","const":false},"seller_identity_verified_by_aico":{"type":"boolean","const":false},"availability_guaranteed":{"type":"boolean","const":false}}}},"required":["request_id","provider_statuses","listings","deal_summary","seller_handoff","truth_boundaries"]},"UsedGoodsDealValidationRequest":{"type":"object","description":"Validate a found used-goods listing against comparable provider/snapshot evidence.","properties":{"title":{"type":"string","examples":["Herman Miller Aeron Size B chair"]},"item_query":{"type":"string","examples":["Herman Miller Aeron Size B"]},"listing_url":{"type":"string","format":"uri"},"price_usd":{"type":"number"},"location":{"type":"string","examples":["sfbay"]},"condition":{"type":"string"},"providers":{"type":"array","items":{"type":"string","enum":["ebay","craigslist"]}},"must_have":{"type":"array","items":{"type":"string"}},"avoid":{"type":"array","items":{"type":"string"}}},"anyOf":[{"required":["title"]},{"required":["item_query"]}],"required":["price_usd"],"additionalProperties":false},"UsedGoodsDealValidationResponse":{"type":"object","description":"Branchable deal validation output: comps, price_vs_market, deal_validation, scam_risk_signals, missing_checks, seller_questions, seller_handoff, and explicit non-checkout/non-escrow/non-verification boundaries.","properties":{"request_id":{"type":"string"},"product":{"type":"string","enum":["used_goods_deal_validation_v0"]},"provider_statuses":{"type":"array","items":{"type":"object","additionalProperties":true}},"comps":{"type":"object","additionalProperties":true},"price_vs_market":{"type":"object","additionalProperties":true},"deal_validation":{"type":"object","additionalProperties":true},"scam_risk_signals":{"type":"array","items":{"type":"string"}},"missing_checks":{"type":"array","items":{"type":"string"}},"seller_questions":{"type":"array","items":{"type":"string"}},"seller_handoff":{"type":"object","additionalProperties":true},"truth_boundaries":{"type":"object","properties":{"aico_checkout_supported":{"type":"boolean","const":false},"aico_escrow_supported":{"type":"boolean","const":false},"seller_identity_verified_by_aico":{"type":"boolean","const":false},"availability_guaranteed":{"type":"boolean","const":false}}}},"required":["request_id","product","provider_statuses","comps","price_vs_market","deal_validation","scam_risk_signals","missing_checks","seller_questions","seller_handoff","truth_boundaries"]},"SkillSearchRequest":{"type":"object","description":"Agent how-to/procedure search request for finding relevant skills before execution.","properties":{"query":{"type":"string","minLength":12,"examples":["best way for an agent to find a skill before coding"]},"max_results":{"type":"number","minimum":1,"maximum":10,"default":5},"sources":{"type":"array","items":{"type":"string","enum":["vercel_labs_skills","aico_skill_library","web_search_pattern"]}}},"required":["query"],"additionalProperties":false},"SkillSearchResponse":{"type":"object","description":"Branchable skill/procedure options with provenance and explicit non-execution boundaries. The response helps agents choose what to inspect next; it does not execute skills or guarantee the globally best option.","properties":{"request_id":{"type":"string"},"product":{"type":"string","enum":["skill_search_v0"]},"query":{"type":"object","additionalProperties":true},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"source":{"type":"string","enum":["vercel_labs_skills","aico_skill_library","web_search_pattern"]},"summary":{"type":"string"},"best_for":{"type":"array","items":{"type":"string"}},"actionability":{"type":"string","enum":["copy_or_adapt_skill","load_existing_skill","run_search_then_verify"]},"confidence":{"type":"string","enum":["high","medium","low"]},"provenance":{"type":"object","additionalProperties":true},"branch_on":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}}},"required":["id","title","source","summary","actionability","confidence","provenance","branch_on","limitations"]}},"next_steps":{"type":"array","items":{"type":"string"}},"truth_boundaries":{"type":"object","properties":{"executes_skill":{"type":"boolean","const":false},"installs_dependencies":{"type":"boolean","const":false},"guarantees_best_option":{"type":"boolean","const":false},"live_web_search":{"type":"boolean","const":false}},"required":["executes_skill","installs_dependencies","guarantees_best_option","live_web_search"]}},"required":["request_id","product","query","options","next_steps","truth_boundaries"]},"AgentLaunchAuditRequest":{"type":"object","description":"Audit a domain/API for agent-launch readiness before spending external scans or submitting to registries.","properties":{"url":{"type":"string","format":"uri"},"product_type":{"type":"string","enum":["agent_api","mcp_server","agent_tool","saas","docs_site"],"default":"agent_api"},"checks":{"type":"array","items":{"type":"string"}},"external_scan_budget":{"type":"object","properties":{"provider":{"type":"string","examples":["ora"]},"max_active_scans":{"type":"number","minimum":0},"next_safe_time":{"type":"string"}},"additionalProperties":false}},"required":["url"],"additionalProperties":false},"AgentLaunchGenerateRequest":{"type":"object","description":"Generate starter agent-discovery surfaces and truth-boundary warnings for a launch target.","properties":{"url":{"type":"string","format":"uri"},"product_name":{"type":"string"},"product_type":{"type":"string","enum":["agent_api","mcp_server","agent_tool","saas","docs_site"],"default":"agent_api"},"capabilities":{"type":"array","items":{"type":"string"}}},"required":["url"],"additionalProperties":false},"AgentLaunchAuditResponse":{"type":"object","description":"Agent Launch Pack output with owned-fixable gaps, external-only blockers, verified surfaces, fix plan, and external scan decision.","properties":{"product":{"type":"string","enum":["agent_launch_pack_v0"]},"scan_id":{"type":"string"},"domain":{"type":"string","format":"uri"},"readiness_score":{"type":"number"},"grade":{"type":"string"},"ready_for_external_scan":{"type":"boolean"},"should_run_external_scan":{"type":"object","additionalProperties":true},"verified_surfaces":{"type":"object","additionalProperties":true},"owned_fixable_gaps":{"type":"array","items":{"type":"object","additionalProperties":true}},"external_only_gaps":{"type":"array","items":{"type":"object","additionalProperties":true}},"fix_plan":{"type":"array","items":{"type":"object","additionalProperties":true}},"truth_boundaries":{"type":"object","additionalProperties":true}},"required":["product","domain","readiness_score","should_run_external_scan","verified_surfaces","owned_fixable_gaps","external_only_gaps","fix_plan","truth_boundaries"]},"AgentLaunchGenerateResponse":{"type":"object","description":"Patch-ready starter files and truth warnings for agent-launch discovery surfaces.","properties":{"product":{"type":"string","enum":["agent_launch_pack_v0"]},"target":{"type":"string","format":"uri"},"files":{"type":"array","items":{"type":"object","additionalProperties":true}},"patches":{"type":"array","items":{"type":"object","additionalProperties":true}},"truth_warnings":{"type":"array","items":{"type":"string"}}},"required":["product","target","files","patches","truth_warnings"]},"AgentProofNotabilityRequest":{"type":"object","description":"Preflight whether an entity has enough first-party and independent proof for Wikipedia/Wikidata/registry-style venues.","properties":{"entity_name":{"type":"string","examples":["Agent Infrastructure Co"]},"url":{"type":"string","format":"uri"},"target_venues":{"type":"array","items":{"type":"string","enum":["wikipedia","wikidata","mcp_registry","ai_tool_directory","package_registry"]}},"evidence_urls":{"type":"array","items":{"type":"string","format":"uri"}},"claims":{"type":"array","items":{"type":"string"}}},"required":["entity_name","url"],"additionalProperties":false},"AgentProofNotabilityResponse":{"type":"object","description":"Agent Proof Graph notability preflight with venue readiness, independent_substantial_sources, first-party sources, trivial mentions, claim graph, and evidence plan.","properties":{"product":{"type":"string","enum":["agent_proof_graph_v0"]},"checked_at":{"type":"string"},"entity":{"type":"object","additionalProperties":true},"ready_to_submit":{"type":"boolean"},"venue_readiness":{"type":"object","additionalProperties":true},"evidence_summary":{"type":"object","properties":{"independent_substantial_sources":{"type":"array","items":{"type":"object","additionalProperties":true}},"self_authored_sources":{"type":"array","items":{"type":"object","additionalProperties":true}},"trivial_mentions":{"type":"array","items":{"type":"object","additionalProperties":true}},"unreachable_sources":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"claim_graph":{"type":"array","items":{"type":"object","additionalProperties":true}},"evidence_plan":{"type":"array","items":{"type":"object","additionalProperties":true}},"safe_next_step":{"type":"string"},"truth_boundaries":{"type":"array","items":{"type":"string"}}},"required":["product","entity","ready_to_submit","venue_readiness","evidence_summary","claim_graph","evidence_plan","safe_next_step","truth_boundaries"]},"ActivationRequest":{"type":"object","description":"Optional metadata for one-request agent activation.","properties":{"agent_name":{"type":"string","examples":["codex-buyer-agent"]},"intended_use":{"type":"string","examples":["Evaluate Agent Travel API from a shell-only benchmark."]},"traffic_type":{"type":"string","enum":["external","smoke_test","test_operational"],"default":"external","description":"Optional operator label for synthetic activation probes. Buyer/evaluator agents should omit this or use external; scheduled production smokes should use smoke_test/test_operational so funnel reporting does not inflate real demand."}},"additionalProperties":false},"ActivationResponse":{"type":"object","description":"Free sandbox activation response. api_key.value is returned exactly once; store it immediately.","properties":{"request_id":{"type":"string"},"account":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"plan":{"type":"string","enum":["free_sandbox"]},"email_verification_required_for_sandbox":{"type":"boolean"},"created_for":{"type":"string","enum":["agent_activation"]},"traffic_type":{"type":"string","enum":["external","smoke_test","test_operational"],"description":"Operator label for funnel reporting; defaults to external for real buyer/evaluator demand."}},"required":["id","email","plan","email_verification_required_for_sandbox","created_for","traffic_type"]},"api_key":{"type":"object","properties":{"id":{"type":"string"},"value":{"type":"string","description":"Returned once; never appears again."},"prefix":{"type":"string","example":"aico_live_"},"returned_once":{"type":"boolean"},"store_immediately":{"type":"boolean"}},"required":["id","value","prefix","returned_once"]},"limits":{"type":"object","properties":{"hourly":{"type":"number","example":10},"monthly":{"type":"number","example":100}},"required":["hourly","monthly"]},"first_call":{"type":"object","additionalProperties":true},"billing_next_step":{"type":"object","additionalProperties":true},"abuse_controls":{"type":"object","additionalProperties":true},"product_truth":{"type":"object","additionalProperties":true}},"required":["request_id","account","api_key","limits","first_call","abuse_controls","product_truth"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false},"FeedbackRequest":{"type":"object","description":"Structured feedback from an agent after a REST or MCP call. Use this to report usefulness, blockers, alternatives, missing handoffs, or confusing provenance.","properties":{"request_id":{"type":"string","description":"Optional request_id from a travel search response."},"rating":{"type":"string","enum":["useful","partially_useful","not_useful","blocked"]},"issue_categories":{"type":"array","minItems":1,"items":{"type":"string","enum":["off_scope","missing_live_data","unclear_provenance","handoff_incomplete","docs_confusing","activation_blocked","pricing_blocked","competitor_preferred","generic_search_preferred","other"]}},"chosen_alternative":{"type":"string","enum":["aico","generic_search","competitor","abandoned","unknown"]},"expected_behavior":{"type":"string"},"actual_behavior":{"type":"string"},"notes":{"type":"string"},"may_contact":{"type":"boolean"}},"required":["rating","issue_categories"],"additionalProperties":false},"FeedbackResponse":{"type":"object","properties":{"feedback_id":{"type":"string"},"stored":{"type":"boolean"},"roadmap_bucket":{"type":"string"},"roadmap_buckets":{"type":"array","description":"Roadmap buckets inferred from the submitted issue_categories.","items":{"type":"string"}},"issue_categories":{"type":"array","items":{"type":"string"}},"received_at":{"type":"string"}},"required":["feedback_id","stored","roadmap_bucket","roadmap_buckets","issue_categories"]},"AgentApiRequest":{"type":"object","description":"Authenticated request from an agent for a new AICO API primitive. If AICO builds an API an agent requests, the requesting account is eligible for $100 of AICO usage credits.","properties":{"requested_api_name":{"type":"string","minLength":12,"description":"Short descriptive name for the requested API."},"problem":{"type":"string","minLength":12,"description":"Concrete agent workflow problem this API would solve."},"use_case":{"type":"string"},"proposed_endpoint":{"type":"string","examples":["/api/v1/tax/import-duty/estimate"]},"expected_inputs":{"type":"array","items":{"type":"string"}},"expected_outputs":{"type":"array","items":{"type":"string"}},"current_workaround":{"type":"string"},"urgency":{"type":"string","enum":["low","medium","high","blocked"],"default":"medium"},"agent_context":{"type":"string"},"may_contact":{"type":"boolean"}},"required":["requested_api_name","problem"],"additionalProperties":false},"AgentApiRequestResponse":{"type":"object","properties":{"accepted":{"type":"boolean","enum":[true]},"stored":{"type":"boolean","enum":[true]},"api_request_id":{"type":"string"},"requested_api_name":{"type":"string"},"roadmap_bucket":{"type":"string","enum":["agent_requested_api"]},"incentive":{"type":"object","properties":{"credit_usd":{"type":"number","enum":[100]},"credit_type":{"type":"string","enum":["usage_credit"]},"condition":{"type":"string","enum":["if_aico_builds_requested_api"]},"note":{"type":"string"}},"required":["credit_usd","credit_type","condition","note"]},"next_step":{"type":"string"},"received_at":{"type":"string"}},"required":["accepted","stored","api_request_id","requested_api_name","roadmap_bucket","incentive","next_step"]},"CommercialIntentRequest":{"type":"object","description":"API-key-authenticated paid-intent bridge from a first-value commercial_next_step response. Records intent before browser-authenticated Stripe Checkout; it does not create checkout, booking inventory, rates, fares, or booking support.","properties":{"request_id":{"type":"string","description":"request_id from the Travel API response that exposed commercial_next_step."},"source_path":{"type":"string","enum":["/api/v1/travel/search/commercial-next-step"],"default":"/api/v1/travel/search/commercial-next-step","description":"Allowlisted commercial_next_step.checkout_source_path from POST /api/v1/travel/search."}},"required":["request_id"],"additionalProperties":false},"CommercialIntentResponse":{"type":"object","description":"Commercial intent was recorded from API-key context. The response points to browser-authenticated billing and preserves beta truth boundaries.","properties":{"commercial_intent_id":{"type":"string"},"event":{"type":"string","enum":["commercial_intent_requested"]},"request_id":{"type":"string"},"source_path":{"type":"string","enum":["/api/v1/travel/search/commercial-next-step"]},"traffic_type":{"type":"string","enum":["external","smoke_test","test_operational"]},"requires_browser_billing_account":{"type":"boolean"},"billing_bridge":{"type":"object","properties":{"status":{"type":"string","enum":["browser_billing_account_required"]},"reason":{"type":"string"},"paid_signup_url":{"type":"string","format":"uri"},"paid_login_url":{"type":"string","format":"uri"},"billing_url_after_login":{"type":"string","format":"uri"}},"required":["status","reason","paid_signup_url","paid_login_url","billing_url_after_login"]},"next_action":{"type":"object","properties":{"type":{"type":"string","enum":["open_browser_authenticated_billing"]},"signup_url":{"type":"string","format":"uri"},"login_url":{"type":"string","format":"uri"}},"required":["type","signup_url","login_url"]},"truth_boundaries":{"type":"object","properties":{"live_booking_inventory":{"type":"boolean","enum":[false]},"provider_backed_rates":{"type":"boolean","enum":[false]},"live_flight_fares":{"type":"boolean","enum":[false]},"booking_supported":{"type":"boolean","enum":[false]}},"required":["live_booking_inventory","provider_backed_rates","live_flight_fares","booking_supported"]}},"required":["commercial_intent_id","event","request_id","source_path","traffic_type","requires_browser_billing_account","billing_bridge","next_action","truth_boundaries"]},"TravelSearchRequest":{"type":"object","properties":{"user_request":{"type":"string","description":"Natural-language trip request. Recommended when the human prompt contains hard scope that may conflict with copied sample JSON, for example Northern California redwoods/coast or Denver, Colorado.","examples":["Plan a trip to somewhere in Northern California for Memorial Day weekend from SFO. Focus on food, hiking, recovery, redwoods, and coast.","Plan a Memorial Day weekend trip to somewhere in Denver, Colorado."]},"query":{"type":"string","description":"Compatibility alias for user_request for shell agents that send a single query string. If both query and user_request are present, user_request wins.","examples":["LangGraph travel agent needs a provider-ready validation handoff for a 3 day restorative Northern California coast trip before live provider fanout."]},"origin":{"type":"string","examples":["SFO"]},"departure_window":{"type":"array","items":{"type":"string","format":"date"},"minItems":2,"maxItems":2,"examples":[["2026-10-01","2026-10-03"]]},"trip_length_days":{"type":"number","examples":[14]},"budget_usd":{"type":"number","examples":[9000]},"interests":{"type":"array","items":{"type":"string"},"examples":[["hiking","food","recovery"]]},"destination_constraints":{"type":"array","description":"Explicit geography or place constraints. Use hard: true for constraints that must filter off-scope destinations before ranking.","items":{"type":"object","properties":{"type":{"type":"string","enum":["region","city","country","state","park","coast"]},"value":{"type":"string","examples":["Northern California","Denver","Colorado"]},"hard":{"type":"boolean","default":true}},"required":["type","value"]},"examples":[[{"type":"region","value":"Northern California","hard":true}]]},"required_themes":{"type":"array","description":"Themes that should be treated as hard/important intent when ranking, such as redwoods and coast.","items":{"type":"string"},"examples":[["redwoods","coast"]]},"strict_mode":{"type":"boolean","description":"When true with hard destination/theme constraints, do not fill results with off-scope destinations just because they score well on generic interests.","examples":[true]},"live_research_mode":{"type":"string","enum":["off","bounded","async_only"],"description":"Controls the strict arbitrary-destination research lifecycle. off returns a research-ready scaffold; bounded may return partial evidence; async_only returns research_pending with a poll_url. None of these imply live booking inventory, provider-backed rates, or live airfare.","examples":["bounded"]},"max_live_research_ms":{"type":"number","minimum":0,"description":"Maximum bounded-research latency in milliseconds. If the budget is too small, responses return research_status.mode=research_pending instead of off-scope fallback.","examples":[7000]},"services":{"type":"array","items":{"type":"string"},"description":"Accepted during beta for response labeling and live place-discovery handoff only. Does not switch on booking inventory, provider-backed hotel rates, or live airfare quotes.","examples":[["flights","stays","weather","research"]]}},"additionalProperties":false},"TravelIntentParseResponse":{"type":"object","description":"REST intent-parse primitive response. Agents can call this before ranking/provider fanout to branch on effective input, interpreted constraints, conflicts, beta warnings, and false live/provider truth boundaries without receiving ranked destinations.","properties":{"product":{"type":"string","enum":["travel_intent_parse_v0"]},"beta_caveat":{"type":"string"},"beta_warnings":{"type":"array","description":"Honest beta caveats including services-label-only behavior and unsupported-origin fallbacks; not a live booking/rate/fare signal.","items":{"type":"string"}},"parsed_intent":{"type":"object","required":["effective_input","interpreted_constraints","constraint_conflicts"],"properties":{"effective_input":{"type":"object","description":"Canonical input after natural-language intent and compatibility aliases are resolved.","additionalProperties":true},"interpreted_constraints":{"type":"object","description":"Agent-readable summary of inferred hard/soft geography, themes, date window, strict mode, and precedence before ranking.","additionalProperties":true},"constraint_conflicts":{"type":"array","description":"Conflict records when copied examples or structured fields conflict with natural-language hard constraints.","items":{"type":"object","additionalProperties":true}}}},"truth_boundaries":{"type":"object","description":"False live/provider-backed truth markers agents must preserve before booking, rate, or fare claims.","required":["live_booking_inventory","provider_backed_rates","live_airfare","booking_supported"],"properties":{"live_booking_inventory":{"type":"boolean","enum":[false]},"provider_backed_rates":{"type":"boolean","enum":[false]},"live_airfare":{"type":"boolean","enum":[false]},"booking_supported":{"type":"boolean","enum":[false]}}}},"required":["product","beta_warnings","parsed_intent","truth_boundaries"]},"TravelDestinationsSearchResponse":{"type":"object","description":"REST destination-search primitive response. Agents use this as the in-scope candidate/no-match gate before live places, plan validation, or provider fanout; it intentionally omits ranked_destinations while exposing match_status, bookability state, provider-handoff summaries, and false live/provider truth boundaries.","properties":{"product":{"type":"string","enum":["travel_destinations_search_v0"]},"beta_caveat":{"type":"string"},"beta_warnings":{"type":"array","items":{"type":"string"}},"interpreted_constraints":{"type":"object","additionalProperties":true},"constraint_conflicts":{"type":"array","items":{"type":"object","additionalProperties":true}},"match_status":{"type":"object","additionalProperties":true},"bookability_status":{"type":"string","enum":["not_bookable","handoff_required"]},"bookability":{"type":"object","additionalProperties":true},"candidate_destinations":{"type":"array","description":"In-scope candidate destinations with eligibility, source tiers, and provider-handoff summaries. These are not live inventory/rate/fare results.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"trip_style":{"type":"string"},"destination_airport":{"type":"string"},"score":{"type":"number"},"eligibility":{"type":"object","additionalProperties":true},"confidence":{"type":"object","additionalProperties":true},"match_reasons":{"type":"array","items":{"type":"string"}},"provider_handoff_summary":{"type":"object","additionalProperties":true}},"required":["id","name","eligibility","provider_handoff_summary"]}},"truth_boundaries":{"type":"object","required":["live_booking_inventory","provider_backed_rates","live_airfare","booking_supported"],"properties":{"live_booking_inventory":{"type":"boolean","enum":[false]},"provider_backed_rates":{"type":"boolean","enum":[false]},"live_airfare":{"type":"boolean","enum":[false]},"booking_supported":{"type":"boolean","enum":[false]}}}},"required":["product","beta_warnings","interpreted_constraints","match_status","bookability_status","candidate_destinations","truth_boundaries"]},"TravelPlacesSearchResponse":{"type":"object","description":"REST live-places primitive response. Agents call this after destination gating for evidence about one selected candidate; live_places evidence is not booking inventory, provider-backed rates, live airfare, or booking support.","properties":{"product":{"type":"string","enum":["travel_places_search_v0"]},"beta_caveat":{"type":"string"},"beta_warnings":{"type":"array","items":{"type":"string"}},"interpreted_constraints":{"type":"object","additionalProperties":true},"constraint_conflicts":{"type":"array","items":{"type":"object","additionalProperties":true}},"match_status":{"type":"object","additionalProperties":true},"selected_candidate":{"type":["object","null"],"additionalProperties":true},"live_places":{"type":["object","null"],"description":"Live-place evidence and coverage for the selected candidate. This is evidence only and does not imply availability, room rates, airfare, checkout, or booking support.","additionalProperties":true},"truth_boundaries":{"type":"object","required":["live_booking_inventory","provider_backed_rates","live_airfare","booking_supported"],"properties":{"live_booking_inventory":{"type":"boolean","enum":[false]},"provider_backed_rates":{"type":"boolean","enum":[false]},"live_airfare":{"type":"boolean","enum":[false]},"booking_supported":{"type":"boolean","enum":[false]}}},"next_step":{"type":"string"}},"required":["product","match_status","selected_candidate","live_places","truth_boundaries"]},"TravelPlanValidateResponse":{"type":"object","description":"REST plan-validation primitive response. Agents call this before provider fanout to validate proposed-plan coherence and unsupported live claims while preserving false live/provider truth boundaries.","properties":{"product":{"type":"string","enum":["travel_plan_validate_v0"]},"beta_caveat":{"type":"string"},"beta_warnings":{"type":"array","items":{"type":"string"}},"interpreted_constraints":{"type":"object","additionalProperties":true},"constraint_conflicts":{"type":"array","items":{"type":"object","additionalProperties":true}},"plan_validation":{"type":"object","description":"Branchable validation result with constraint satisfaction, candidate_intent_coherence, unsupported_live_claims, provider_validation_required, required_external_checks, and validation_checklist.","additionalProperties":true},"truth_boundaries":{"type":"object","required":["live_booking_inventory","provider_backed_rates","live_airfare","booking_supported"],"properties":{"live_booking_inventory":{"type":"boolean","enum":[false]},"provider_backed_rates":{"type":"boolean","enum":[false]},"live_airfare":{"type":"boolean","enum":[false]},"booking_supported":{"type":"boolean","enum":[false]}}},"next_step":{"type":"string"}},"required":["product","plan_validation","truth_boundaries"]},"TravelProviderHandoffsGenerateResponse":{"type":"object","description":"REST provider-handoff primitive response. Agents call this to generate provider-ready flight/hotel/place handoff objects and required external checks; it does not claim booking support, live booking inventory, provider-backed rates, live airfare, final price, or lowest connected-supplier price.","properties":{"product":{"type":"string","enum":["travel_provider_handoffs_generate_v0"]},"beta_caveat":{"type":"string"},"beta_warnings":{"type":"array","items":{"type":"string"}},"interpreted_constraints":{"type":"object","additionalProperties":true},"constraint_conflicts":{"type":"array","items":{"type":"object","additionalProperties":true}},"match_status":{"type":"object","additionalProperties":true},"selected_candidate":{"type":["object","null"],"additionalProperties":true},"bookability_status":{"type":"string","enum":["not_bookable","handoff_required"]},"provider_handoffs":{"type":["object","null"],"additionalProperties":true},"required_external_checks":{"type":"array","items":{"type":"string"}},"truth_boundaries":{"type":"object","required":["live_booking_inventory","provider_backed_rates","live_airfare","booking_supported"],"properties":{"live_booking_inventory":{"type":"boolean","enum":[false]},"provider_backed_rates":{"type":"boolean","enum":[false]},"live_airfare":{"type":"boolean","enum":[false]},"booking_supported":{"type":"boolean","enum":[false]}}}},"required":["product","match_status","bookability_status","provider_handoffs","truth_boundaries"]},"TravelResearchEvidence":{"type":"object","description":"Cited research evidence for arbitrary-destination travel handoffs. Evidence can come from the Exa evidence cache or another search/provider adapter; it is not live booking inventory, provider-backed rates, live airfare, or checkout support.","properties":{"category":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"source":{"type":"string","enum":["exa","cache","operator_snapshot","other_search"]},"retrieved_at":{"type":"string","format":"date-time"},"freshness_days":{"type":"number"},"confidence":{"type":"string","enum":["low","medium","high"]},"supports":{"type":"array","items":{"type":"string"}},"caveats":{"type":"array","items":{"type":"string"}}},"required":["category","title","url","source","retrieved_at","freshness_days","confidence","supports","caveats"]},"TravelResearchJobStatus":{"type":"object","description":"Pollable progressive research status for arbitrary-destination Travel API jobs. Running/pending jobs are useful contracts, not failures; agents should use completed evidence when present and provider handoffs otherwise.","properties":{"job_id":{"type":"string"},"status":{"type":"string","enum":["running","partial","complete","failed"]},"destination":{"type":"string"},"coverage_mode":{"type":"string","enum":["research_pending","research_partial","research_complete_enough"]},"completed_categories":{"type":"array","items":{"type":"string"}},"pending_categories":{"type":"array","items":{"type":"string"}},"failed_categories":{"type":"array","items":{"type":"object","additionalProperties":true}},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/TravelResearchEvidence"}},"provider":{"type":"object","additionalProperties":true},"safe_to_use_as_final_plan":{"type":"boolean"},"bookability":{"type":"object","additionalProperties":true},"next_actions":{"type":"array","items":{"type":"string"}},"assembled_response_hint":{"type":"string"}},"required":["job_id","status","destination","coverage_mode","completed_categories","pending_categories","evidence","safe_to_use_as_final_plan","bookability","next_actions"]},"TravelSearchResponse":{"type":"object","properties":{"request_id":{"type":"string"},"feedback_prompt":{"type":"object","description":"Agent-readable pointer for submitting structured feedback tied to this response.","properties":{"endpoint":{"type":"string","enum":["/api/v1/feedback"]},"request_id":{"type":"string"},"prompt":{"type":"string"}},"required":["endpoint","request_id","prompt"]},"commercial_next_step":{"type":"object","nullable":true,"description":"Agent-readable paid upgrade handoff shown only on matched responses after coherent first value or provider-ready handoff value. no_match responses return null so the API does not pitch payment when hard constraints are unsupported.","properties":{"reason":{"type":"string","enum":["coherent_first_value_or_provider_handoff_ready"]},"prompt":{"type":"string"},"recommended_plan":{"type":"string","enum":["hobby"]},"paid_signup_url":{"type":"string","format":"uri"},"paid_login_url":{"type":"string","format":"uri"},"billing_url_after_login":{"type":"string","format":"uri"},"requires_browser_billing_account":{"type":"boolean"},"checkout_source_path":{"type":"string","enum":["/api/v1/travel/search/commercial-next-step"]},"source_attribution":{"type":"object","properties":{"surface":{"type":"string","enum":["travel_rest_or_mcp_first_value"]},"request_id":{"type":"string","nullable":true},"event":{"type":"string","enum":["commercial_next_step_presented"]}},"required":["surface","request_id","event"]},"commercial_intent_action":{"type":"object","description":"Immediate API-key-authenticated next call a shell/MCP agent can make to record paid intent from this first-value response before browser-authenticated billing.","properties":{"method":{"type":"string","enum":["POST"]},"endpoint":{"type":"string","enum":["/api/v1/commercial/intent"]},"auth":{"type":"string","enum":["bearer_api_key"]},"body":{"type":"object","properties":{"request_id":{"type":"string","nullable":true},"source_path":{"type":"string","enum":["/api/v1/travel/search/commercial-next-step"]}},"required":["request_id","source_path"]},"expected_event":{"type":"string","enum":["commercial_intent_requested"]},"requires_browser_billing_account":{"type":"boolean"}},"required":["method","endpoint","auth","body","expected_event","requires_browser_billing_account"]},"api_request_action":{"type":"object","description":"Optional authenticated demand-capture next call when a missing primitive blocks adoption after first value; this records agent_requested_api demand without guaranteeing AICO will build it.","properties":{"method":{"type":"string","enum":["POST"]},"endpoint":{"type":"string","enum":["/api/v1/api-requests"]},"auth":{"type":"string","enum":["bearer_api_key"]},"roadmap_bucket":{"type":"string","enum":["agent_requested_api"]},"use_when":{"type":"string","enum":["missing_primitive_blocks_adoption_after_first_value"]},"conditional_incentive":{"type":"string","enum":["$100 usage credit eligibility if AICO builds an API the agent requested"]}},"required":["method","endpoint","auth","roadmap_bucket","use_when","conditional_incentive"]},"limits_delta":{"type":"object","properties":{"free_sandbox":{"type":"object","properties":{"hourly":{"type":"number"},"monthly":{"type":"number"}},"required":["hourly","monthly"]},"hobby":{"type":"object","properties":{"hourly":{"type":"number"},"monthly":{"type":"number"}},"required":["hourly","monthly"]},"remaining_now":{"type":"object","properties":{"hourly":{"type":"number","nullable":true},"monthly":{"type":"number","nullable":true}},"required":["hourly","monthly"]}},"required":["free_sandbox","hobby","remaining_now"]},"truth_boundaries":{"type":"object","properties":{"live_booking_inventory":{"type":"boolean"},"provider_backed_rates":{"type":"boolean"},"live_flight_fares":{"type":"boolean"},"booking_supported":{"type":"boolean"}},"required":["live_booking_inventory","provider_backed_rates","live_flight_fares","booking_supported"]}},"required":["reason","prompt","recommended_plan","paid_signup_url","paid_login_url","billing_url_after_login","requires_browser_billing_account","checkout_source_path","source_attribution","commercial_intent_action","api_request_action","limits_delta","truth_boundaries"]},"requested_services":{"type":"array","items":{"type":"string"}},"beta_warnings":{"type":"array","description":"Honest beta caveats including services-label-only behavior and when unsupported origins fall back to default model_estimate flight values.","items":{"type":"string"}},"interpreted_constraints":{"type":"object","description":"Agent-readable summary of how the API interpreted natural-language and structured hard constraints before ranking.","properties":{"destination_region":{"type":"string","nullable":true},"destination_city":{"type":"string","nullable":true},"hard_destination_constraints":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}}}},"required_themes":{"type":"array","items":{"type":"string"}},"date_window":{"type":"array","items":{"type":"string"},"nullable":true},"strict_mode":{"type":"boolean"},"precedence":{"type":"string"}}},"constraint_conflicts":{"type":"array","description":"Conflict records when copied examples or structured fields conflict with natural-language hard constraints; the user request wins in strict-mode planning.","items":{"type":"object","properties":{"field":{"type":"string"},"provided_value":{"type":"string"},"interpreted_value":{"type":"string"},"resolution":{"type":"string","enum":["user_request_wins"]}}}},"match_status":{"type":"object","description":"Top-level match/no-match state. Strict hard geography with missing curated_baseline coverage can return matched research_handoff candidates instead of no_match or unrelated fallback destinations.","properties":{"status":{"type":"string","enum":["matched","no_match"]},"reason":{"type":"string","enum":["hard_constraints_satisfied","ranked_candidates_available","unsupported_coverage","empty_ranked_set"]},"hard_constraints":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}}}},"required_themes":{"type":"array","items":{"type":"string"}},"recommended_next_tool":{"type":"string","enum":["live_search_or_provider_search"]},"provider_validation_required":{"type":"boolean"},"source_tiers":{"type":"array","items":{"type":"string"}},"validation_checklist":{"type":"array","items":{"type":"string"}}},"required":["status","reason","hard_constraints","required_themes","provider_validation_required","source_tiers"]},"bookability_status":{"type":"string","enum":["not_bookable","handoff_required","provider_live_partial","provider_live_verified"],"description":"Top-level normalized booking readiness for the whole response. no_match responses return not_bookable; matched curated_baseline or research_handoff beta responses return handoff_required until provider-backed inventory/rates/fares exist."},"bookability":{"type":"object","description":"Top-level normalized bookability state agents can branch on before inspecting result-level handoffs or attempting live provider validation.","required":["status","source_tier","live_booking_inventory","provider_backed_rates","live_airfare","booking_supported","provider_validation_required","next_step"],"properties":{"status":{"type":"string","enum":["not_bookable","handoff_required","provider_live_partial","provider_live_verified"]},"status_enum":{"type":"array","items":{"type":"string","enum":["not_bookable","handoff_required","provider_live_partial","provider_live_verified"]}},"source_tier":{"type":"string","enum":["unsupported","research_handoff","handoff_required"]},"live_booking_inventory":{"type":"boolean"},"provider_backed_rates":{"type":"boolean"},"live_airfare":{"type":"boolean"},"booking_supported":{"type":"boolean","enum":[false]},"provider_validation_required":{"type":"boolean"},"next_step":{"type":"string","enum":["run_live_search_or_provider_search","execute_provider_handoffs"]},"why_not_bookable_yet":{"type":"string"}}},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"coverage_mode":{"type":"string","enum":["curated_ready","research_ready","research_pending","research_partial","research_complete_enough"],"description":"Destination intelligence mode. Arbitrary strict destinations can be accepted globally via research_ready/research_pending rather than no_match."},"research_status":{"type":"object","description":"Progressive research lifecycle for arbitrary destinations: cache/freshness state, completed/pending categories, poll_url, Exa provider availability, and safe partial-return contract.","additionalProperties":true},"coverage":{"type":"object","description":"Coverage strength by tier; destination_supported can be true even when curated_strength is none because AICO can return research/provider handoffs for anywhere.","additionalProperties":true},"evidence":{"type":"array","description":"Normalized live/cached evidence records when available. Empty means research is pending or disabled, not that the destination is unsupported.","items":{"type":"object","additionalProperties":true}},"score":{"type":"number"},"total_trip_estimate_usd":{"type":"number"},"ranking_breakdown":{"type":"object","properties":{"budget_fit":{"type":"number"},"interest_fit":{"type":"number"},"weather_fit":{"type":"number"},"flight_fit":{"type":"number"},"duration_fit":{"type":"number"},"remote_work_fit":{"type":"number","description":"curated_baseline/model_estimate suitability score for remote-work and long-stay intent; not live internet/coworking validation."},"family_fit":{"type":"number","description":"curated_baseline/model_estimate family-trip suitability score; not live room occupancy, transfer, or neighborhood safety validation."},"event_fit":{"type":"number","description":"curated_baseline/model_estimate sports/event-trip suitability score; not live event schedule, ticket, venue-safety, or hotel-compression validation."}}},"remote_work_snapshot":{"type":"object","description":"curated_baseline/model_estimate remote-work and long-stay suitability. This is not live internet measurement, visa advice, lodging availability, or coworking inventory.","properties":{"suitability_score":{"type":"number"},"time_zone_overlap_with_california":{"type":"string"},"internet_reliability":{"type":"string"},"coworking_access":{"type":"string"},"walkability":{"type":"string"},"monthly_stay_usd":{"type":"string"},"long_stay_notes":{"type":"string"},"workday_validation_handoff":{"type":"string","description":"Explicit handoff for validating timezone overlap, workday hours, internet reliability, coworking access, and neighborhood routine with live/local sources."},"official_stay_rule_next_step":{"type":"string","description":"Explicit handoff for official visa, passport, tax/work-permission, and stay-limit validation before a long stay."},"validation_checklist":{"type":"array","items":{"type":"string"}},"blocked_reasons":{"type":"array","items":{"type":"string"}},"recommended_next_tool":{"type":"string","enum":["live_local_workation_and_official_stay_sources"]},"official_validation_required":{"type":"boolean"},"provenance":{"type":"string"}}},"family_snapshot":{"type":"object","description":"curated_baseline/model_estimate family-trip and party-size costing suitability. This is not live room occupancy, kid-friendly lodging availability, transfer guarantees, or neighborhood safety validation.","properties":{"assumed_travelers":{"type":"number"},"assumed_children":{"type":"number"},"party_size_cost_estimate_usd":{"type":"number"},"family_fit_score":{"type":"number"},"child_friendly_signal":{"type":"string"},"transfer_friction":{"type":"string"},"safety_signal":{"type":"string"},"provenance":{"type":"string"}}},"accessibility_snapshot":{"type":"object","description":"curated_baseline/model_estimate accessibility hard-constraint transparency and validation handoff. This is not live accessible-room, step-free transit, attraction-access, or medical suitability data.","properties":{"constraint_handling":{"type":"string"},"accessibility_decision_summary":{"type":"string"},"validation_checklist":{"type":"array","items":{"type":"string"}},"recommended_next_tool":{"type":"string","enum":["official_accessibility_or_live_local_provider"]},"blocked_reasons":{"type":"array","items":{"type":"string"}},"official_validation_required":{"type":"boolean"},"step_free_transit_status":{"type":"string"},"accessible_lodging_status":{"type":"string"},"transfer_friction":{"type":"string"},"weather_mobility_note":{"type":"string"},"provenance":{"type":"string"}}},"visa_stay_snapshot":{"type":"object","description":"curated_baseline/model_estimate visa and stay-rule transparency. This is not legal or immigration advice and requires official validation.","properties":{"stay_length_days":{"type":"number"},"visa_rule_status":{"type":"string"},"official_validation_required":{"type":"boolean"},"relevance":{"type":"string"},"provenance":{"type":"string"}}},"multi_city_snapshot":{"type":"object","description":"curated_baseline/model_estimate multi-city logistics transparency with choice rationale for the top baseline option. This is not provider-backed rail schedules, hotel neighborhoods, rates, availability, or booking inventory.","properties":{"logistics_mode":{"type":"string"},"rail_or_transfer_notes":{"type":"string"},"neighborhood_guidance_status":{"type":"string"},"price_confidence":{"type":"string"},"selected_choice_summary":{"type":"string"},"why_top_result_wins":{"type":"array","items":{"type":"string"}},"compared_option_names":{"type":"array","items":{"type":"string"}},"live_validation_required":{"type":"boolean"},"validation_checklist":{"type":"array","items":{"type":"string"}},"blocked_reasons":{"type":"array","items":{"type":"string"}},"recommended_next_tool":{"type":"string","enum":["live_rail_hotel_and_local_area_providers"]},"provider_validation_required":{"type":"boolean"},"suggested_planning_use":{"type":"string"},"provenance":{"type":"string"}}},"event_snapshot":{"type":"object","description":"curated_baseline/model_estimate event-trip transparency. This is not live event schedule, hotel compression, venue safety, ticket, or provider availability data.","properties":{"event_context_status":{"type":"string"},"event_timing_input_status":{"type":"string"},"seeded_venue_context":{"type":"string"},"schedule_risk":{"type":"string"},"schedule_risk_level":{"type":"string","enum":["low","medium","high","unknown"]},"hotel_compression":{"type":"string"},"hotel_compression_risk_level":{"type":"string","enum":["low","medium","medium_high","high","unknown"]},"post_event_safety":{"type":"string"},"neighborhood_safety_handoff":{"type":"string"},"backup_activity_guidance":{"type":"string"},"backup_activity_candidates":{"type":"array","items":{"type":"string"}},"venue_validation_handoff":{"type":"string"},"short_window_flight_note":{"type":"string"},"requested_window":{"type":["array","null"],"items":{"type":"string"}},"live_validation_required":{"type":"boolean"},"provenance":{"type":"string"}}},"match_reasons":{"type":"array","items":{"type":"string"}},"confidence":{"type":"object","properties":{"level":{"type":"string","enum":["low","medium","high"]},"score":{"type":"number","minimum":0,"maximum":1},"reasons":{"type":"array","items":{"type":"string"}}}},"booking_readiness":{"type":"object","description":"Agent-readable boundary between ranking use and live-provider validation. Agent Travel API can rank destinations, but cannot validate rooms, airfare, provider-backed rates, or availability.","properties":{"can_rank_destinations":{"type":"boolean"},"can_validate_live_rooms":{"type":"boolean"},"can_validate_current_airfare":{"type":"boolean"},"can_quote_provider_rates":{"type":"boolean"},"requires_live_validation":{"type":"boolean"},"recommended_next_tool":{"type":"string","enum":["live_search_or_booking_provider"]},"inventory_validation_handoff":{"type":"object","description":"Explicit handoff for agents to validate airfare, room availability, provider rates, and total taxes/fees before booking. This is a validation checklist, not live inventory.","properties":{"status":{"type":"string","enum":["required_before_booking"]},"next_tool":{"type":"string","enum":["live_search_or_booking_provider"]},"validates":{"type":"array","items":{"type":"string"}},"reason":{"type":"string"},"validation_checklist":{"type":"array","items":{"type":"string"}}}},"blocked_reasons":{"type":"array","items":{"type":"string"}},"notes":{"type":"array","items":{"type":"string"}}}},"bookability_status":{"type":"string","enum":["not_bookable","handoff_required","provider_live_partial","provider_live_verified"],"description":"Normalized current booking readiness. In this beta, ranked results are handoff_required until provider-backed availability/rates/fares are integrated."},"bookability":{"type":"object","description":"Normalized bookability state agents can branch on before attempting checkout or provider validation.","required":["status","source_tier","live_booking_inventory","provider_backed_rates","live_airfare","booking_supported","provider_validation_required","next_step"],"properties":{"status":{"type":"string","enum":["not_bookable","handoff_required","provider_live_partial","provider_live_verified"]},"status_enum":{"type":"array","items":{"type":"string","enum":["not_bookable","handoff_required","provider_live_partial","provider_live_verified"]}},"source_tier":{"type":"string","enum":["handoff_required"]},"live_booking_inventory":{"type":"boolean"},"provider_backed_rates":{"type":"boolean"},"live_airfare":{"type":"boolean"},"booking_supported":{"type":"boolean","enum":[false]},"provider_validation_required":{"type":"boolean"},"next_step":{"type":"string","enum":["execute_provider_handoffs"]},"why_not_bookable_yet":{"type":"string"}}},"provider_handoffs":{"type":"object","description":"Provider-ready search handoffs for live validation after AICO ranking. These are generated params, URLs, and checklists for downstream providers; they are not live airfare, booking inventory, or provider-backed rates.","properties":{"bookability_status":{"type":"string","enum":["handoff_required"]},"provider_status":{"type":"string","enum":["pending_credentials","sandbox","unavailable","provider_live"],"description":"Provider capability status for the handoff object. Current public beta defaults to pending_credentials/unavailable until real supplier credentials and production verification exist."},"capabilities":{"type":"object","description":"Provider-neutral capability contract. Current beta values remain false until real supplier rails verify inventory, rates, fares, booking support, and connected-supplier price comparison.","properties":{"live_booking_inventory":{"type":"boolean","enum":[false]},"provider_backed_rates":{"type":"boolean","enum":[false]},"live_flight_fares":{"type":"boolean","enum":[false]},"booking_supported":{"type":"boolean","enum":[false]},"lowest_connected_supplier_price":{"type":"boolean","enum":[false]}}},"bookability":{"type":"object","properties":{"status":{"type":"string","enum":["handoff_required","not_bookable","provider_live_partial","provider_live_verified"]},"checkout_owner":{"type":"string","enum":["external_provider","aico"]},"requires_price_check":{"type":"boolean"},"final_price_guaranteed":{"type":"boolean","enum":[false]},"provider_checkout_url":{"type":["string","null"]},"last_checked_at":{"type":["string","null"]},"quote_expires_at":{"type":["string","null"]}}},"fare_status":{"type":"object","properties":{"status":{"type":"string","enum":["unavailable","pending_credentials","sandbox","provider_live"]},"source_tier":{"type":"string","enum":["handoff_required","unsupported","provider_live"]},"last_checked_at":{"type":["string","null"]},"quote_expires_at":{"type":["string","null"]}}},"rate_status":{"type":"object","properties":{"status":{"type":"string","enum":["unavailable","pending_credentials","sandbox","provider_live"]},"source_tier":{"type":"string","enum":["handoff_required","unsupported","provider_live"]},"last_checked_at":{"type":["string","null"]},"quote_expires_at":{"type":["string","null"]}}},"lowest_price_selection":{"type":"object","description":"Connected-supplier lowest-price selection readiness. Current beta is not_available until at least two connected supplier quotes are price-checked, normalized to total price, and retained as evidence for the same request.","properties":{"status":{"type":"string","enum":["not_available","eligible_after_provider_price_checks"]},"connected_supplier_count":{"type":"integer"},"price_checked_supplier_count":{"type":"integer"},"minimum_suppliers_required":{"type":"integer","enum":[2]},"normalized_total_price_required":{"type":"boolean","enum":[true]},"evidence_retention_required":{"type":"boolean","enum":[true]},"reason":{"type":"string"}}},"provider_adapters":{"type":"array","description":"Env-gated live provider adapter status for Amadeus Self-Service Flights (`amadeus_self_service_flights`), Amadeus Self-Service Hotels (`amadeus_self_service_hotels`), Duffel, Expedia Rapid, Hotelbeds, Skyscanner affiliate flight handoffs (`skyscanner_affiliate_flights`), Kiwi/Tequila affiliate flight handoffs (`kiwi_tequila_affiliate_flights`), Travelpayouts affiliate flight handoffs (`travelpayouts_affiliate_flights`), Booking affiliate hotel handoffs (`booking_affiliate_hotels`), Priceline affiliate hotel handoffs (`priceline_affiliate_hotels`), Agoda affiliate hotel handoffs (`agoda_affiliate_hotels`), and Trip.com affiliate hotel handoffs (`tripcom_affiliate_hotels`). Missing credentials return pending_credentials and all provider capability booleans remain false; adapter or affiliate presence is not a live booking/rate/fare, checkout, or lowest-price claim.","items":{"type":"object","required":["provider","category","provider_status","env","missing_env","capabilities","live_provider_call_enabled","checkout_owner","requires_price_check","final_price_guaranteed","provider_checkout_url","last_checked_at","quote_expires_at","next_step","claim_boundary"],"properties":{"provider":{"type":"string","enum":["amadeus_self_service_flights","amadeus_self_service_hotels","duffel_flights","expedia_rapid_hotels","hotelbeds_hotels","skyscanner_affiliate_flights","kiwi_tequila_affiliate_flights","travelpayouts_affiliate_flights","booking_affiliate_hotels","priceline_affiliate_hotels","agoda_affiliate_hotels","tripcom_affiliate_hotels"]},"category":{"type":"string","enum":["flight_fares","flight_booking","hotel_rates_inventory"]},"provider_status":{"type":"string","enum":["pending_credentials","sandbox","provider_live"]},"env":{"type":["string","null"],"enum":["sandbox","production",null]},"missing_env":{"type":"array","items":{"type":"string"}},"capabilities":{"type":"object","required":["live_booking_inventory","provider_backed_rates","live_flight_fares","booking_supported","lowest_connected_supplier_price"],"properties":{"live_booking_inventory":{"type":"boolean","enum":[false]},"provider_backed_rates":{"type":"boolean","enum":[false]},"live_flight_fares":{"type":"boolean","enum":[false]},"booking_supported":{"type":"boolean","enum":[false]},"lowest_connected_supplier_price":{"type":"boolean","enum":[false]}}},"live_provider_call_enabled":{"type":"boolean"},"checkout_owner":{"type":"string","enum":["external_provider","aico","none"]},"requires_price_check":{"type":"boolean","enum":[true]},"final_price_guaranteed":{"type":"boolean","enum":[false]},"provider_checkout_url":{"type":["string","null"]},"last_checked_at":{"type":["string","null"]},"quote_expires_at":{"type":["string","null"]},"next_step":{"type":"string","enum":["provide_credentials_before_provider_calls","run_provider_adapter_smoke_before_claim_graduation"]},"claim_boundary":{"type":"string"}}}},"required_external_checks":{"type":"array","items":{"type":"string"}},"provider_capability_readiness":{"type":"object","description":"Runtime aggregate of provider-adapter claim graduation/readiness for shell agents. Mirrors the launch-readiness eval contract so callers can branch on machine-readable claim_graduation (all false in current beta) and claim_readiness (required_evidence per branch) without parsing every adapter. claim_boundary_regression_count must be 0; non-zero values indicate the underlying smoke leaked a pre-graduation claim and the public/runtime claim must remain false.","required":["claim_graduation","claim_readiness","claim_graduation_blockers","claim_boundary_regression_count","truth_boundary"],"properties":{"claim_graduation":{"type":"object","required":["live_flight_fares","provider_backed_hotel_rates","live_booking_inventory","booking_supported","checkout_supported_by_aico","final_price_guaranteed","lowest_connected_supplier_price"],"properties":{"live_flight_fares":{"type":"boolean","enum":[false]},"provider_backed_hotel_rates":{"type":"boolean","enum":[false]},"live_booking_inventory":{"type":"boolean","enum":[false]},"booking_supported":{"type":"boolean","enum":[false]},"checkout_supported_by_aico":{"type":"boolean","enum":[false]},"final_price_guaranteed":{"type":"boolean","enum":[false]},"lowest_connected_supplier_price":{"type":"boolean","enum":[false]}}},"claim_readiness":{"type":"object","additionalProperties":true},"claim_graduation_blockers":{"type":"array","items":{"type":"string"}},"claim_boundary_regression_count":{"type":"integer","enum":[0]},"claim_boundary_regressions":{"type":"array","items":{"type":"string"}},"provider_smoke_evidence":{"type":"array","items":{"type":"string"}},"missing_env_names":{"type":"array","items":{"type":"string"}},"provider_count":{"type":"integer"},"configured_provider_count":{"type":"integer"},"pending_credential_provider_count":{"type":"integer"},"live_provider_call_enabled_count":{"type":"integer"},"request_sent_count":{"type":"integer"},"external_checkout_handoff_provider_count":{"type":"integer"},"truth_boundary":{"type":"string"}}},"flight_handoff":{"type":"object","properties":{"source_tier":{"type":"string","enum":["handoff_required"]},"provider_status":{"type":"string","enum":["pending_credentials","sandbox","unavailable","provider_live"]},"live_airfare":{"type":"boolean","enum":[false]},"fare_status":{"type":"object","additionalProperties":true},"checkout_owner":{"type":"string","enum":["external_provider","aico"]},"requires_price_check":{"type":"boolean"},"final_price_guaranteed":{"type":"boolean","enum":[false]},"provider_checkout_url":{"type":["string","null"]},"last_checked_at":{"type":["string","null"]},"quote_expires_at":{"type":["string","null"]},"origin":{"type":"string"},"destination_airport":{"type":"string"},"departure_window":{"type":["array","null"],"items":{"type":"string"}},"provider_search_params":{"type":"object","properties":{"origin":{"type":"string"},"destination":{"type":"string"},"date_window":{"type":["array","null"],"items":{"type":"string"}},"travelers":{"type":"string"}}},"search_url":{"type":"string"},"validation_checklist":{"type":"array","items":{"type":"string"}}}},"hotel_handoff":{"type":"object","properties":{"source_tier":{"type":"string","enum":["handoff_required"]},"provider_status":{"type":"string","enum":["pending_credentials","sandbox","unavailable","provider_live"]},"live_booking_inventory":{"type":"boolean","enum":[false]},"provider_backed_rates":{"type":"boolean","enum":[false]},"rate_status":{"type":"object","additionalProperties":true},"checkout_owner":{"type":"string","enum":["external_provider","aico"]},"requires_price_check":{"type":"boolean"},"final_price_guaranteed":{"type":"boolean","enum":[false]},"provider_checkout_url":{"type":["string","null"]},"last_checked_at":{"type":["string","null"]},"quote_expires_at":{"type":["string","null"]},"destination_area":{"type":"string"},"check_in":{"type":["string","null"]},"check_out":{"type":["string","null"]},"party_assumptions":{"type":"string"},"provider_search_params":{"type":"object","properties":{"destination":{"type":"string"},"check_in":{"type":["string","null"]},"check_out":{"type":["string","null"]},"travelers":{"type":"string"},"filters":{"type":"array","items":{"type":"string"}}}},"search_url":{"type":"string"},"validation_checklist":{"type":"array","items":{"type":"string"}}}},"place_handoff":{"type":"object","properties":{"source_tier":{"type":"string","enum":["handoff_required"]},"categories":{"type":"array","items":{"type":"string"}},"search_params":{"type":"object","properties":{"query":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}}}},"search_url":{"type":"string"},"validation_checklist":{"type":"array","items":{"type":"string"}}}}}},"unsupported_constraints":{"type":"array","items":{"type":"string"}},"why_not_bookable_yet":{"type":"string"},"intelligence_basis":{"type":"array","items":{"type":"string"}},"place_candidates":{"type":"object","description":"curated_baseline or research_handoff place candidates for itinerary handoff; handoff_required for live availability, current hours, current park status, and provider-backed prices.","properties":{"lodging":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"why":{"type":"string"},"evidence_basis":{"type":"string","enum":["curated_baseline","research_handoff"],"description":"Source/provenance tier for curated place handoff candidates; currently curated_baseline, not live availability or provider-backed pricing."},"validation_needed":{"type":"string"}}}},"food":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"why":{"type":"string"},"evidence_basis":{"type":"string","enum":["curated_baseline","research_handoff"],"description":"Source/provenance tier for curated place handoff candidates; currently curated_baseline, not live availability or provider-backed pricing."},"validation_needed":{"type":"string"}}}},"hikes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"why":{"type":"string"},"evidence_basis":{"type":"string","enum":["curated_baseline","research_handoff"],"description":"Source/provenance tier for curated place handoff candidates; currently curated_baseline, not live availability or provider-backed pricing."},"validation_needed":{"type":"string"}}}},"route_stops":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"why":{"type":"string"},"evidence_basis":{"type":"string","enum":["curated_baseline","research_handoff"],"description":"Source/provenance tier for curated place handoff candidates; currently curated_baseline, not live availability or provider-backed pricing."},"validation_needed":{"type":"string"}}}},"limitations":{"type":"array","items":{"type":"string"}}}},"suggested_itinerary":{"type":"object","description":"curated_baseline or research_handoff itinerary scaffold for turning ranked destinations into a day-by-day handoff; handoff_required for live restaurant hours, trail status, room availability, traffic, and provider-backed pricing.","properties":{"days":{"type":"array","items":{"type":"object","properties":{"day":{"type":"number"},"title":{"type":"string"},"morning":{"type":"string"},"afternoon":{"type":"string"},"evening":{"type":"string"}}}},"limitations":{"type":"array","items":{"type":"string"}}}},"research_summary":{"type":"string","description":"Research-first summary used when the requested destination is outside stronger curated_baseline coverage."},"research_plan":{"type":"object","description":"Executable web/provider research plan for arbitrary destinations; can be upgraded to Exa or other search-backed evidence when configured.","additionalProperties":true},"research_provider_readiness":{"type":"object","additionalProperties":true},"live_signals":{"type":"object","description":"Live hotel/place discovery signals when available. These are not booking inventory, provider-backed rates, or live flight fares.","properties":{"status":{"type":"string","enum":["live","not_requested","unavailable"]},"source":{"type":"string","enum":["google_places","openstreetmap","none"]},"cache_status":{"type":"string","enum":["hit","miss","bypass"],"description":"For Google Places signals, hit means AICO served short-lived cached duplicate-suppression results without spending a new SearchText request; retrieved_at is freshness metadata, not live availability."},"retrieved_at":{"type":["string","null"]},"query":{"type":["string","null"]},"hotel_candidates":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"source":{"type":"string"},"category":{"type":"string","enum":["lodging","food","things_to_do"]},"address":{"type":"string"},"rating":{"type":"number"},"review_count":{"type":"number"},"website":{"type":"string"},"maps_url":{"type":"string"}}}},"place_candidates":{"type":"object","description":"Live Google Places candidates grouped by category. Lodging candidates remain mirrored in hotel_candidates for backward compatibility.","properties":{"lodging":{"type":"array","items":{"type":"object","additionalProperties":true}},"food":{"type":"array","items":{"type":"object","additionalProperties":true}},"things_to_do":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"coverage":{"type":"object","properties":{"live_hotel_listings":{"type":"boolean"},"live_place_categories":{"type":"array","items":{"type":"string","enum":["lodging","food","things_to_do"]}},"live_booking_inventory":{"type":"boolean","description":"True only for provider-backed booking inventory; AICO-operated Google aggregator snapshots do not set this."},"provider_backed_rates":{"type":"boolean","description":"True only for provider-backed hotel rates; aggregator hotel snapshots do not set this."},"live_flight_fares":{"type":"boolean","description":"True only for provider-backed fare verification; Google Flights aggregator snapshots do not set this."},"aggregator_fare_snapshots":{"type":"boolean","description":"AICO-operated Google Flights aggregator fare snapshot evidence is available, but it is not live airfare, booking inventory, or provider-backed checkout."},"hotel_rate_snapshots":{"type":"boolean","description":"AICO-operated Google hotel rate snapshot evidence is available, but it is not provider-backed rates, booking inventory, or room availability."},"live_hotel_rate_snapshots":{"type":"boolean","deprecated":true,"description":"Deprecated compatibility alias for hotel_rate_snapshots. Snapshot evidence is not provider-backed rates, booking inventory, or room availability."}}},"google_aggregator_signals":{"type":"object","description":"Optional AICO-operated Google Flights/Hotels aggregator snapshots. These are not provider-backed inventory, live airfare, or verified hotel rates.","properties":{"source":{"type":"string","enum":["aico_google_travel_scraper"]},"retrieved_at":{"type":"string"},"aggregator_fare_snapshots":{"type":"array","items":{"type":"object","additionalProperties":true}},"hotel_rate_snapshots":{"type":"array","items":{"type":"object","additionalProperties":true}},"bookability":{"type":"object","required":["live_booking_inventory","provider_backed_rates","live_flight_fares","booking_provider_required"],"properties":{"live_booking_inventory":{"type":"boolean","enum":[false]},"provider_backed_rates":{"type":"boolean","enum":[false]},"live_flight_fares":{"type":"boolean","enum":[false]},"booking_provider_required":{"type":"boolean","enum":[true]}}},"limitations":{"type":"array","items":{"type":"string"}}}},"limitations":{"type":"array","items":{"type":"string"}}}}}}}},"required":["request_id","requested_services","beta_warnings","match_status","bookability_status","bookability","results"]},"DestinationsResponse":{"type":"object","properties":{"request_id":{"type":"string"},"destinations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"region":{"type":"string"},"tripStyle":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"highlights":{"type":"array","items":{"type":"string"}},"researchSummary":{"type":"string"},"intelligence_basis":{"type":"array","items":{"type":"string"}},"coverage":{"type":"object","properties":{"live_booking":{"type":"boolean"},"provider_quotes":{"type":"boolean"},"seeded_flight_origins":{"type":"array","items":{"type":"string"}},"weather_granularity":{"type":"string"},"cost_model":{"type":"string"}}}}}}},"required":["request_id","destinations"]},"AccountMeResponse":{"type":"object","properties":{"request_id":{"type":"string"},"account":{"type":"object","description":"Account plan/source state for the current key, including sandbox activation provenance when applicable so shell agents can verify low-quota activation before first value.","properties":{"plan":{"type":"string","enum":["free_sandbox","free","active","past_due","canceled"]},"created_for":{"type":"string","enum":["agent_activation","dashboard"]},"traffic_type":{"type":["string","null"],"enum":["external","smoke_test","test_operational",null]}},"required":["plan","created_for","traffic_type"]},"api_key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"usage":{"type":"object","description":"Rate-limit and usage details for the current API key.","additionalProperties":true}},"required":["request_id","account","api_key","usage"]}}},"security":[{"bearerAuth":[]}],"paths":{"/api/v1/activation":{"post":{"operationId":"activateSandboxAccount","tags":["activation"],"summary":"Create a free sandbox account and API key","description":"Machine-completable activation path for shell-only agents. Creates a free sandbox account and returns the first bearer API key exactly once, without browser signup, mailbox verification, dashboard cookies, or payment. Sandbox calls are still rate-limited and production billing remains a separate authenticated upgrade step.","security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivationRequest"}}}},"responses":{"201":{"description":"Free sandbox account and one-time API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivationResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Activation attempt limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/goods/search":{"post":{"operationId":"searchUsedGoodsListings","tags":["goods"],"summary":"Search normalized used-goods listings","description":"Searches eBay Browse API first and authorized Craigslist snapshots, then returns normalized listing evidence, deal validation, and seller handoff guidance. AICO does not guarantee availability, verify seller identity, provide escrow, or support checkout yet.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsedGoodsSearchRequest"}}}},"responses":{"200":{"description":"Normalized used-goods listings and deal validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsedGoodsSearchResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/goods/deal/validate":{"post":{"operationId":"validateUsedGoodsDeal","tags":["goods"],"summary":"Validate a used-goods deal against comps","description":"Validates a found listing against comparable eBay Browse API provider evidence and authorized Craigslist snapshots, returning price_vs_market, deal_validation, scam_risk_signals, missing_checks, and seller handoff guidance. AICO does not guarantee availability, verify seller identity, provide escrow, support checkout, or own marketplace inventory.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsedGoodsDealValidationRequest"}}}},"responses":{"200":{"description":"Deal validation, comps, risk signals, and seller handoff","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsedGoodsDealValidationResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/skills/search":{"post":{"operationId":"searchAgentSkills","tags":["skills"],"summary":"Search skill libraries for agent procedures","description":"Returns branchable skill/procedure options from curated skill libraries for agents asking the best way to do something or find something out. v0 includes Vercel Labs find-skills provenance and AICO local skill-library entries; it does not execute selected skills, install dependencies, guarantee the globally best option, or perform live web search yet.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillSearchRequest"}}}},"responses":{"200":{"description":"Ranked skill/procedure options with provenance and truth boundaries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillSearchResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/agent-launch/audit":{"post":{"operationId":"auditAgentLaunchReadiness","tags":["agent-launch"],"summary":"Audit agent-launch readiness for a domain or API","description":"Deterministically checks owned agent-discovery surfaces such as OpenAPI, llms.txt, status.json, pricing, MCP metadata, agent manifests, robots, sitemap, and trust pages. Separates owned_fixable_gaps from external_only_gaps such as MCP registry, skills registry, package registries, AI platform stores, Wikipedia/Wikidata, and third-party mentions. Does not run active external scans or claim third-party acceptance.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLaunchAuditRequest"}}}},"responses":{"200":{"description":"Launch audit with verified surfaces and fix plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLaunchAuditResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/agent-launch/generate":{"post":{"operationId":"generateAgentLaunchPack","tags":["agent-launch"],"summary":"Generate patch-ready agent-launch discovery artifacts","description":"Returns starter files and patch guidance for llms.txt, .well-known/agent.json, status.json, AGENTS.md, and discovery metadata. Includes truth warnings so agents do not fabricate OAuth, registry, package, Wikipedia/Wikidata, provider inventory, checkout, escrow, or verification claims.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLaunchGenerateRequest"}}}},"responses":{"200":{"description":"Generated files, patches, and truth warnings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLaunchGenerateResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/agent-launch/verify":{"post":{"operationId":"verifyAgentLaunchSurfaces","tags":["agent-launch"],"summary":"Verify live launch surfaces after deploy","description":"Fetches deterministic owned surfaces after deployment and returns ready_for_external_scan, remaining_owned_gaps, remaining_external_todos, and should_run_external_scan. Use before spending scarce Ora/ORank-style active scans.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLaunchAuditRequest"}}}},"responses":{"200":{"description":"Launch verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLaunchAuditResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/proof/notability/preflight":{"post":{"operationId":"preflightAgentNotability","tags":["agent-proof"],"summary":"Preflight notability and proof readiness for agent-discoverable entities","description":"Classifies evidence as first-party, independent substantial, trivial, or unreachable; builds a claim graph; and preflights venue readiness for Wikipedia, Wikidata, MCP registries, AI directories, and package registries. Does not publish pages, guarantee venue acceptance, submit listings, or fabricate notability.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentProofNotabilityRequest"}}}},"responses":{"200":{"description":"Proof/notability preflight with venue readiness and evidence plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentProofNotabilityResponse"}}}},"400":{"description":"Invalid or unsafe request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/travel/intent/parse":{"post":{"operationId":"parseTravelIntent","tags":["travel"],"summary":"Parse travel intent without ranking destinations","description":"REST primitive for agents that need normalized effective_input, interpreted_constraints, constraint_conflicts, and beta_warnings before choosing a destination-search or provider-handoff path. It does not return ranked destinations and does not imply live booking inventory, provider-backed rates, live airfare, or booking support.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TravelSearchRequest"}}}},"responses":{"200":{"description":"Parsed travel intent with branchable truth boundaries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TravelIntentParseResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/travel/destinations/search":{"post":{"operationId":"searchTravelDestinationsPrimitive","tags":["travel"],"summary":"Search in-scope travel destinations without ranked payload bloat","description":"REST primitive equivalent to MCP travel.destinations.search. It gates candidate destinations by interpreted constraints before live places, plan validation, or provider fanout, returning match_status, bookability_status, provider_handoff_summary, and false live booking/rate/fare truth boundaries without ranked_destinations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TravelSearchRequest"}}}},"responses":{"200":{"description":"Destination candidate gate with branchable match/bookability state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TravelDestinationsSearchResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/travel/places/search":{"post":{"operationId":"searchTravelPlacesPrimitive","tags":["travel"],"summary":"Search live place evidence for one in-scope travel candidate","description":"REST primitive equivalent to MCP travel.places.search. It takes the original travel request plus an optional candidate_id or destination_name and returns selected_candidate, live_places evidence, match_status, next_step, and false live booking/rate/fare truth boundaries without ranked_destinations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TravelSearchRequest"}}}},"responses":{"200":{"description":"Live-place evidence for the selected candidate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TravelPlacesSearchResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/travel/plan/validate":{"post":{"operationId":"validateTravelPlanPrimitive","tags":["travel"],"summary":"Validate proposed travel plan coherence before provider fanout","description":"REST primitive equivalent to MCP travel.plan.validate. It checks proposed_plan against interpreted constraints, date/theme coherence, and unsupported live-provider claims, returning plan_validation and false live booking/rate/fare truth boundaries without ranking destinations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TravelSearchRequest"}}}},"responses":{"200":{"description":"Plan validation with coherence checks and provider-validation requirements","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TravelPlanValidateResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/travel/provider_handoffs/generate":{"post":{"operationId":"generateTravelProviderHandoffsPrimitive","tags":["travel"],"summary":"Generate provider-ready travel handoffs without booking claims","description":"REST primitive equivalent to MCP travel.provider_handoffs.generate. It returns selected_candidate, bookability_status, provider_handoffs, required_external_checks, and false live booking/rate/fare truth boundaries so agents can fan out to their own supplier stack.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TravelSearchRequest"}}}},"responses":{"200":{"description":"Provider-ready handoff objects and required external checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TravelProviderHandoffsGenerateResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/travel/search":{"post":{"operationId":"searchTravelDestinations","tags":["travel"],"summary":"Search ranked travel destinations","description":"Returns structured destination rankings based on origin, departure window, trip length, budget, interests, and optional hard natural-language/geography/theme constraints such as user_request, destination_constraints, required_themes, and strict_mode.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TravelSearchRequest"}}}},"responses":{"200":{"description":"Ranked travel results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TravelSearchResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/travel/research/jobs/{id}":{"get":{"operationId":"getTravelResearchJobStatus","tags":["travel"],"summary":"Poll arbitrary-destination travel research status","description":"Returns progressive research status for a strict arbitrary destination. A running job is a useful partial-return contract: preserve destination scope, use completed evidence if present, and keep live booking/rate/fare claims false until provider validation.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^research_[a-z0-9_]+_[a-z0-9]{1,12}$"}}],"responses":{"200":{"description":"Travel research job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TravelResearchJobStatus"}}}},"404":{"description":"Unknown or invalid research job id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/demo/travel/sample":{"get":{"operationId":"getTravelDemoSample","tags":["travel"],"summary":"Get an unauthenticated sample Travel API response","description":"Returns a static, unauthenticated Travel API sample response for autonomous agents that can only perform GET discovery before activation. Live calls still require bearer API-key authentication; the sample preserves false live booking inventory, provider-backed rates, live airfare, checkout, escrow, and seller-verification truth boundaries.","security":[],"responses":{"200":{"description":"Sample Travel API response shape with branchable truth boundaries","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"product":{"type":"string"},"authentication_required_for_live_calls":{"type":"boolean"},"activation_endpoint":{"type":"string","format":"uri"},"match_status":{"type":"object","additionalProperties":true},"bookability_status":{"type":"string","enum":["handoff_required"]},"candidate_destinations":{"type":"array","items":{"type":"object","additionalProperties":true}},"truth_boundaries":{"type":"object","additionalProperties":{"type":"boolean"}}},"required":["request_id","product","authentication_required_for_live_calls","activation_endpoint","match_status","bookability_status","candidate_destinations","truth_boundaries"]}}}}}}},"/api/v1/feedback":{"post":{"operationId":"submitAgentFeedback","tags":["feedback"],"summary":"Submit structured agent feedback","description":"Authenticated feedback endpoint for agents to report whether a REST/MCP response was useful, blocked, missing live data, unclear on provenance, or missing a provider handoff. This captures demand and product blockers without implying live booking inventory, provider-backed rates, or live airfare.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackRequest"}}}},"responses":{"200":{"description":"Feedback stored and mapped to roadmap buckets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackResponse"}}}},"400":{"description":"Invalid feedback payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/api-requests":{"post":{"operationId":"requestAgentNativeApi","tags":["feedback"],"summary":"Request a new agent-native API","description":"Authenticated endpoint for agents to request new AICO API primitives. Requests are roadmap evidence; if AICO builds an API an agent requests, the requesting account is eligible for $100 of AICO usage credits. This does not guarantee every requested API will be built.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentApiRequest"}}}},"responses":{"201":{"description":"API request stored with usage-credit incentive details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentApiRequestResponse"}}}},"400":{"description":"Invalid API request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/commercial/intent":{"post":{"operationId":"recordCommercialIntent","tags":["commercial"],"summary":"Record API-key commercial intent before browser billing","description":"Authenticated bridge for shell/API-key agents that received a first-value commercial_next_step and want paid access. Records commercial_intent_requested with source attribution, then returns paid signup/login URLs and explicit requires_browser_billing_account without creating checkout or claiming live booking inventory, provider-backed rates, live airfare, or booking support.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialIntentRequest"}}}},"responses":{"200":{"description":"Commercial intent recorded; browser-authenticated billing is still required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialIntentResponse"}}}},"400":{"description":"Invalid commercial intent payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/travel/destinations":{"get":{"operationId":"listTravelDestinations","tags":["travel"],"summary":"List supported destinations","responses":{"200":{"description":"Supported destinations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationsResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/account/me":{"get":{"operationId":"inspectAccountUsage","tags":["account"],"summary":"Inspect the authenticated API key","responses":{"200":{"description":"Current key and usage data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountMeResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}