{"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.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 Hobby when a $5/mo flat recurring subscription is useful. 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":{"price_usd_month":5,"pricing_model":"flat_recurring_subscription","billing_model_note":"not metered usage billing","metered_usage_billing":false,"checkout":"Self-serve Stripe Checkout after login"},"enterprise":{"pricing_model":"custom_commitment","contact":"agent@agentinfrastructureco.com"},"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":"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"]},"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]},"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},"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"]},"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","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. When strict hard geography or required themes have no in-scope curated_baseline candidate, this returns no_match with unsupported_coverage instead of 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 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.","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","handoff_required"]},"live_booking_inventory":{"type":"boolean"},"provider_backed_rates":{"type":"boolean"},"live_airfare":{"type":"boolean"},"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"},"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.","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"},"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"]},"required_external_checks":{"type":"array","items":{"type":"string"}},"flight_handoff":{"type":"object","properties":{"source_tier":{"type":"string","enum":["handoff_required"]},"live_airfare":{"type":"boolean"},"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"]},"live_booking_inventory":{"type":"boolean"},"provider_backed_rates":{"type":"boolean"},"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 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"},"validation_needed":{"type":"string"}}}},"food":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"why":{"type":"string"},"evidence_basis":{"type":"string"},"validation_needed":{"type":"string"}}}},"hikes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"why":{"type":"string"},"evidence_basis":{"type":"string"},"validation_needed":{"type":"string"}}}},"route_stops":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"why":{"type":"string"},"evidence_basis":{"type":"string"},"validation_needed":{"type":"string"}}}},"limitations":{"type":"array","items":{"type":"string"}}}},"suggested_itinerary":{"type":"object","description":"curated_baseline 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"}}}},"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"]},"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."},"live_hotel_rate_snapshots":{"type":"boolean","description":"AICO-operated Google hotel rate snapshot evidence is available, but it is not provider-backed rates 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","properties":{"live_booking_inventory":{"type":"boolean","enum":[false]},"provider_backed_rates":{"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":{"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":{"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":{"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":{"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/travel/search":{"post":{"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/feedback":{"post":{"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":{"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":{"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":{"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":{"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"}}}}}}}}}