{ "openapi": "3.1.0", "info": { "title": "TravelMindsAI API Gateway", "description": "Customer-facing gateway for the TravelMindsAI dataset. Auth via Bearer API keys for data endpoints; session JWT for dashboard endpoints. Hosted billing via Paddle (international) and Razorpay (India). Rate-limit + quota enforced per plan.", "version": "0.13.0" }, "paths": { "/v1/freshness": { "get": { "tags": [ "freshness" ], "summary": "Get Freshness", "description": "Return per-watcher freshness summary.", "operationId": "get_freshness_v1_freshness_get", "parameters": [ { "name": "watcher", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "filter to one watcher_kind", "title": "Watcher" }, "description": "filter to one watcher_kind" }, { "name": "scope", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "filter to one watcher_scope", "title": "Scope" }, "description": "filter to one watcher_scope" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Freshness V1 Freshness Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/licenses": { "get": { "tags": [ "public" ], "summary": "Full TMAIV2 license registry", "description": "Promoted from the inline main.py handler. Returns the same shape.", "operationId": "list_licenses_v1_licenses_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Response List Licenses V1 Licenses Get" } } } } } } }, "/v1/licenses/audit": { "get": { "tags": [ "public" ], "summary": "Per-endpoint + per-marketplace-channel license posture", "description": "Live attestation that mirrors legal/license_attestation_v1.json.\n\nComposes:\n - The static per-endpoint license map.\n - Active rows from tmai_marketplace_publications, joined to the\n canonical subset license list.\n - Publication channels not yet active are still surfaced so a\n reviewer can see the planned coverage.", "operationId": "audit_v1_licenses_audit_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Audit V1 Licenses Audit Get" } } } } } } }, "/dashboard/sva.html": { "get": { "tags": [ "public" ], "summary": "SVA operator console", "description": "Render the SVA console HTML.", "operationId": "sva_dashboard_dashboard_sva_html_get", "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } }, { "name": "x-tmai-console-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Console-Token" } }, { "name": "tmai_console_token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tmai Console Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "text/html": { "schema": { "type": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/dashboard/sva/queue.html": { "get": { "tags": [ "public" ], "summary": "SVA queue — review / edit / skip upcoming slots", "operationId": "sva_queue_page_dashboard_sva_queue_html_get", "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } }, { "name": "x-tmai-console-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Console-Token" } }, { "name": "tmai_console_token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tmai Console Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "text/html": { "schema": { "type": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/dashboard/sva/queue/skip": { "post": { "tags": [ "public" ], "summary": "Write a declined marker for a slot", "operationId": "sva_queue_skip_dashboard_sva_queue_skip_post", "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } }, { "name": "x-tmai-console-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Console-Token" } }, { "name": "tmai_console_token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tmai Console Token" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Body_sva_queue_skip_dashboard_sva_queue_skip_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/dashboard/sva/queue/edit": { "post": { "tags": [ "public" ], "summary": "Replace the body of a queued slot", "operationId": "sva_queue_edit_dashboard_sva_queue_edit_post", "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } }, { "name": "x-tmai-console-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Console-Token" } }, { "name": "tmai_console_token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tmai Console Token" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Body_sva_queue_edit_dashboard_sva_queue_edit_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/dashboard/sdr.html": { "get": { "tags": [ "public" ], "summary": "SDR operator console", "operationId": "sdr_dashboard_dashboard_sdr_html_get", "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } }, { "name": "x-tmai-console-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Console-Token" } }, { "name": "tmai_console_token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tmai Console Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "text/html": { "schema": { "type": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/dashboard/sdr/feedback": { "post": { "tags": [ "public" ], "summary": "Record founder feedback on a prospect", "operationId": "post_feedback_dashboard_sdr_feedback_post", "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } }, { "name": "x-tmai-console-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Console-Token" } }, { "name": "tmai_console_token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tmai Console Token" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Body_post_feedback_dashboard_sdr_feedback_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/dashboard/sdr/status": { "post": { "tags": [ "public" ], "summary": "Update a prospect's pipeline status", "operationId": "post_status_dashboard_sdr_status_post", "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } }, { "name": "x-tmai-console-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Console-Token" } }, { "name": "tmai_console_token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tmai Console Token" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Body_post_status_dashboard_sdr_status_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/dashboard/sdr/drafts.html": { "get": { "tags": [ "public" ], "summary": "Loop B drafts queue — approve / skip / edit in place", "operationId": "drafts_page_dashboard_sdr_drafts_html_get", "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } }, { "name": "x-tmai-console-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Console-Token" } }, { "name": "tmai_console_token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tmai Console Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "text/html": { "schema": { "type": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/dashboard/sdr/drafts/{draft_id}/approve": { "post": { "tags": [ "public" ], "summary": "Mark a Loop B draft approved for sending", "operationId": "post_draft_approve_dashboard_sdr_drafts__draft_id__approve_post", "parameters": [ { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Draft Id" } }, { "name": "token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } }, { "name": "x-tmai-console-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Console-Token" } }, { "name": "tmai_console_token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tmai Console Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/dashboard/sdr/drafts/{draft_id}/skip": { "post": { "tags": [ "public" ], "summary": "Mark a Loop B draft skipped (no send)", "operationId": "post_draft_skip_dashboard_sdr_drafts__draft_id__skip_post", "parameters": [ { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Draft Id" } }, { "name": "token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } }, { "name": "x-tmai-console-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Console-Token" } }, { "name": "tmai_console_token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tmai Console Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/dashboard/sdr/drafts/{draft_id}/edit": { "post": { "tags": [ "public" ], "summary": "Replace draft body before send", "operationId": "post_draft_edit_dashboard_sdr_drafts__draft_id__edit_post", "parameters": [ { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Draft Id" } }, { "name": "token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } }, { "name": "x-tmai-console-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Console-Token" } }, { "name": "tmai_console_token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tmai Console Token" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Body_post_draft_edit_dashboard_sdr_drafts__draft_id__edit_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/healthz": { "get": { "tags": [ "public" ], "summary": "Liveness probe — returns gateway version, no DB touch", "description": "Lightweight uptime check. Returns gateway version + service name. Does not touch the Postgres pool. Use this for load-balancer health checks and uptime monitors (StatusCake, Pingdom, etc.).", "operationId": "healthz_healthz_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/v1/plans": { "get": { "tags": [ "public" ], "summary": "List active plan tiers with pricing and quotas", "description": "Source of truth for the pricing-page renderer. Returns every active plan with monthly_request_quota, rate_limit_per_minute, and per-currency pricing (USD + INR, monthly + annual). Public endpoint, no auth required.", "operationId": "list_plans_v1_plans_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PlanOut" }, "type": "array", "title": "Response List Plans V1 Plans Get" } } } } } } }, "/v1/signup": { "post": { "tags": [ "auth" ], "summary": "Create an account in pending_verify status; queue verification email", "description": "Registers a new account, queues an email-verification message into tmai_email_outbox (the worker dispatches within ~1 minute), and returns the new account_id. billing_country is ISO-3166 alpha-2 — used by checkout when BILLING_PROVIDER_MODE='country' (currently 'paddle' by default, see /v1/checkout).", "operationId": "signup_v1_signup_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupBody" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/verify-email": { "post": { "tags": [ "auth" ], "summary": "Consume an email-verification token from the verify link", "description": "Flips email_verified=true on the account and schedules a D+1 onboarding email. Idempotent — re-verifying produces zero rows because the token is nulled on first call.", "operationId": "verify_email_v1_verify_email_post", "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/login": { "post": { "tags": [ "auth" ], "summary": "Verify password and issue access + refresh tokens", "description": "Verifies the password (Argon2id), records the session in tmai_sessions, and returns a 1h access JWT plus a 30-day refresh token. Use the access token as Authorization: Bearer for session-authenticated routes.", "operationId": "login_v1_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginBody" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/refresh": { "post": { "tags": [ "auth" ], "summary": "Rotate the refresh token; mint a fresh access + refresh pair", "description": "Validates the supplied refresh token, replaces the stored hash, and issues a new access JWT + new refresh token. The old refresh token stops working immediately (rotation pattern — limits damage on leak).", "operationId": "refresh_v1_refresh_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshBody" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/forgot-password": { "post": { "tags": [ "auth" ], "summary": "Email a 2-hour password-reset token", "description": "Always returns {sent: true} even on unknown emails to prevent account enumeration. On a real match, queues a password-reset email with a single-use token valid for 2 hours.", "operationId": "forgot_password_v1_forgot_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordBody" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reset-password": { "post": { "tags": [ "auth" ], "summary": "Consume reset token, set new password, revoke all sessions", "description": "Accepts a reset token + new password. On success: hashes the new password with Argon2id, clears the reset token, and revokes ALL active sessions for the account (forces re-login from every device — best practice after credential rotation).", "operationId": "reset_password_v1_reset_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordBody" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/api-keys": { "post": { "tags": [ "account" ], "summary": "Create an API key — full secret returned once, never again", "description": "Generates a new API key shaped tmai_live_<8hex>.<32urlsafe>. The full key is returned in api_key on this response only; subsequent reads via GET /v1/api-keys return key_prefix only. Store the full key securely on creation.", "operationId": "create_api_key_v1_api_keys_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "account" ], "summary": "List the calling account's API keys (prefixes only)", "description": "Returns each key's id, name, key_prefix, and timestamps. The full secret is never returned — the server only stores its argon2 hash. Sorted newest-first.", "operationId": "list_api_keys_v1_api_keys_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyOut" }, "title": "Response List Api Keys V1 Api Keys Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/api-keys/{key_id}": { "delete": { "tags": [ "account" ], "summary": "Soft-revoke an API key (sets revoked_at)", "description": "Idempotent revocation — re-revoking a revoked key returns 404. The key row is preserved (revoked_at timestamp set) for audit. Subsequent requests with this key return 401.", "operationId": "revoke_api_key_v1_api_keys__key_id__delete", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/account": { "get": { "tags": [ "account" ], "summary": "Snapshot of the account: profile, active subscription, current-month usage", "description": "Returns account profile, active subscription (or null on free tier), and this calendar month's request_count + bytes_returned + remaining quota. Drives the dashboard home screen.", "operationId": "get_account_v1_account_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountView" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onboarding/event": { "post": { "tags": [ "account" ], "summary": "Record completion of an onboarding tutorial step", "description": "Idempotent — re-recording the same event is a no-op. Used by the dashboard tutorial widget when the user creates their first key, makes their first call, etc.", "operationId": "record_onboarding_event_v1_onboarding_event_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingEventBody" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onboarding/state": { "get": { "tags": [ "account" ], "summary": "Return the dashboard onboarding tutorial state", "description": "Returns the list of all ONBOARDING_STEPS, each annotated as completed or not. Some steps (api_key_created, first_call, concierge_tried) are auto-detected from existing tables — the user doesn't have to POST an event for those.", "operationId": "get_onboarding_state_v1_onboarding_state_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/usage": { "get": { "tags": [ "account" ], "summary": "Detailed usage for the dashboard — daily series + top endpoints", "description": "Returns the current calendar month's usage at daily granularity, the top-5 endpoints by call count, and a 7-day extrapolation used by the dashboard to prompt for an upgrade ahead of quota exhaustion. Use this for the in-dashboard usage chart; use /v1/account for the lighter summary that drives the home screen.", "operationId": "get_usage_detailed_v1_usage_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/checkout": { "post": { "tags": [ "billing" ], "summary": "Create a hosted-checkout session (Paddle by default; configurable)", "description": "Provider is chosen by BILLING_PROVIDER_MODE: 'paddle' (default, all customers cleared through Paddle as Merchant of Record), 'razorpay' (force Razorpay for all), or 'country' (route IN -> Razorpay, else -> Paddle). plan_id='enterprise' returns a mailto: contact-sales URL.", "operationId": "create_checkout_v1_checkout_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutBody" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/me": { "get": { "tags": [ "data" ], "summary": "Live snapshot of plan + quota for the calling key/session", "description": "Cheapest way to read your live counters programmatically. Returns plan_id, quota, used, remaining, and rate_limit_per_minute. Counts as 1 quota call — if you only need the headers, read them off your next real request instead.", "operationId": "me_v1_me_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/cities": { "get": { "tags": [ "data" ], "summary": "Curated cities ranked by a composite desirability score", "description": "Filtered by country (iso_alpha2) and minimum score (min_score). The child_city_count and aggregates_neighborhoods markers indicate which rows are megacity rollups (NYC, London, Paris, Tokyo). tier_version pins against a specific quarterly snapshot for reproducibility (default = current; see /v1/cities/tier-versions).", "operationId": "get_cities_v1_cities_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } }, { "name": "iso_alpha2", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso Alpha2" } }, { "name": "min_score", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Min Score" } }, { "name": "tier_version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tier Version" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CityOut" }, "title": "Response Get Cities V1 Cities Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/cities/tier-versions": { "get": { "tags": [ "data" ], "summary": "List ranking-snapshot versions", "description": "Returns the available tier_version values, with row count and min/max score per version. Pin /v1/cities?tier_version=N for reproducible queries across quarterly rebuilds.", "operationId": "get_tier_versions_v1_cities_tier_versions_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/cities/{city_id}/similar": { "get": { "tags": [ "data" ], "summary": "Cities most similar to a destination", "description": "Returns the K cities most similar to the anchor by similarity-embedding cosine distance (a learned geographic + thematic city embedding, ~135K-city coverage). Captures character/setting similarity ('cities like this one'), not just geographic proximity. Backs the Concierge similar-destinations tool; exposed here as a direct developer endpoint.", "operationId": "get_similar_cities_v1_cities__city_id__similar_get", "parameters": [ { "name": "city_id", "in": "path", "required": true, "schema": { "type": "string", "title": "City Id" } }, { "name": "k", "in": "query", "required": false, "schema": { "type": "integer", "default": 8, "title": "K" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/pois/{poi_id}/nearby": { "get": { "tags": [ "data" ], "summary": "Nearest POIs to an anchor POI", "description": "Top-K nearest POIs to an anchor, from a nightly-materialised proximity index. Sub-200ms. Backs the Concierge nearby-POIs tool; exposed here as a direct developer endpoint.", "operationId": "get_nearby_pois_endpoint_v1_pois__poi_id__nearby_get", "parameters": [ { "name": "poi_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Poi Id" } }, { "name": "k", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "title": "K" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/pois": { "get": { "tags": [ "data" ], "summary": "Points of interest, ranked by quality, significance, and knowledge-base grounding", "description": "Returns curated POIs (utility/duplicate/tribute/corrupted classes filtered out). Ordering is internal: editorial quality, then significance (world-heritage > national > regional), then strength of knowledge-base grounding, then rating. When city_id is a megacity that has neighborhood children (e.g. New York City), results are automatically rolled up from those children. With no city_id or iso_alpha2 filter, returns a curated sample of verified heritage POIs (scope by city_id or iso_alpha2 for full results).", "operationId": "get_pois_v1_pois_get", "parameters": [ { "name": "city_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City Id" } }, { "name": "iso_alpha2", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso Alpha2" } }, { "name": "has_qid", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Qid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/POIOut" }, "title": "Response Get Pois V1 Pois Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/hotels": { "get": { "tags": [ "data" ], "summary": "Hotels for a city, ranked by rating then curation richness", "description": "Ordering: rating DESC > metadata.rating DESC > quality_class > presence of curation flags (notable_for, style, booking_url) > data_quality. Megacity rollup applies to city_id queries (e.g. New York City returns hotels from all NYC boroughs).", "operationId": "get_hotels_v1_hotels_get", "parameters": [ { "name": "city_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City Id" } }, { "name": "iso_alpha2", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso Alpha2" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LodgingOut" }, "title": "Response Get Hotels V1 Hotels Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/restaurants": { "get": { "tags": [ "data" ], "summary": "Restaurants for a city, ranked by guide tier then rating", "description": "Ordering: guide tier (3-star > 2-star > 1-star > value-pick > listed > none) > rating DESC > quality_class > curation richness (notable_for, description) > data_quality. Guide tier is the dominant signal where present (~19k restaurants); rating-based ranking applies otherwise. Megacity rollup applies to city_id (e.g. Paris aggregates from arrondissements).", "operationId": "get_restaurants_v1_restaurants_get", "parameters": [ { "name": "city_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City Id" } }, { "name": "iso_alpha2", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso Alpha2" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LodgingOut" }, "title": "Response Get Restaurants V1 Restaurants Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/experiences": { "get": { "tags": [ "data" ], "summary": "Curated experiences (excludes hotels/utilities/banks/offices/transit/retail)", "description": "Ordering: rating DESC NULLS LAST. View `experiences_curated` applies a 12-category POSIX exclusion regex to filter out non-experience venues. Megacity rollup applies.", "operationId": "get_experiences_v1_experiences_get", "parameters": [ { "name": "city_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City Id" } }, { "name": "iso_alpha2", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso Alpha2" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LodgingOut" }, "title": "Response Get Experiences V1 Experiences Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/visa": { "get": { "tags": [ "data" ], "summary": "Visa rules between two countries (78,804 country-pair edges)", "description": "Backed by visa_matrix (W109). Pass passport and/or destination as country code or English name (case-insensitive). requirement is one of visa_free, visa_on_arrival, e_visa, visa_required, no_admission.", "operationId": "get_visa_v1_visa_get", "parameters": [ { "name": "passport", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Passport" } }, { "name": "destination", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Destination" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VisaOut" }, "title": "Response Get Visa V1 Visa Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/scores/{city_id}": { "get": { "tags": [ "data" ], "summary": "Full composite-score row for a city: master + sub-scores + derived indices", "description": "Returns master_score, social/connectivity/NPS/value sub-scores, dimensions_scored, and the seven derived indices (family / luxury / adventure / retirement / weekend-getaway / overtourism-risk / best-fit). Length 0 if the city has no score row.", "operationId": "get_city_score_v1_scores__city_id__get", "parameters": [ { "name": "city_id", "in": "path", "required": true, "schema": { "type": "string", "title": "City Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreOut" }, "title": "Response Get City Score V1 Scores City Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/narratives/{city_id}": { "get": { "tags": [ "data" ], "summary": "Hallucination-checked LLM narratives for a city, ordered by section", "description": "Filtered to the v2 prompt family (2.x) and hallucination_check=true with score-leak / quarantine flags excluded. The W9 v2 multilingual gate uses unidecode + WikidataLabelLayer so Hindi / Japanese / Tamil rows pass through the same check as English. Optional ?section= filter.", "operationId": "get_narratives_v1_narratives__city_id__get", "parameters": [ { "name": "city_id", "in": "path", "required": true, "schema": { "type": "string", "title": "City Id" } }, { "name": "section", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Section" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NarrativeOut" }, "title": "Response Get Narratives V1 Narratives City Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/cities/{city_id}/context": { "get": { "tags": [ "data" ], "summary": "India-enriched context bundle for a city — admin, airport, ASI heritage, circuits", "description": "The dense object the Concierge agent's get_city_context tool also calls. Returns admin (state / district / region), nearest airport, ASI monument count + nearby heritage (≤25, India only), tourism circuit memberships, rail stop count, sentiment (paid tier only), and inventory counts.", "operationId": "get_city_context_v1_cities__city_id__context_get", "parameters": [ { "name": "city_id", "in": "path", "required": true, "schema": { "type": "string", "title": "City Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/unesco": { "get": { "tags": [ "data" ], "summary": "UNESCO World Heritage Sites — 2,432 unique across 167 countries", "description": "Deduped on (site_name, country_id) preferring rows that carry coordinates, then earliest created_at. Optional iso_alpha2 filter and in_danger boolean. Ordered by year_inscribed DESC.", "operationId": "get_unesco_v1_unesco_get", "parameters": [ { "name": "iso_alpha2", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso Alpha2" } }, { "name": "in_danger", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "In Danger" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UNESCOOut" }, "title": "Response Get Unesco V1 Unesco Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/circuits": { "get": { "tags": [ "data" ], "summary": "List the canonical India tourism circuits", "description": "15 named multi-city heritage / spiritual / coastal circuits (buddhist-circuit, golden-triangle, char-dham, kerala-backwaters, etc.). Each row has slug, name, description, ideal_duration_days, best_season, and the states[] traversed.", "operationId": "list_circuits_v1_circuits_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CircuitOut" }, "title": "Response List Circuits V1 Circuits Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/circuits/{slug}": { "get": { "tags": [ "data" ], "summary": "Circuit detail with member cities in sequence order", "description": "Same fields as CircuitOut plus members[] in sequence_no order, each linked back to a TMAIV2 city UUID where possible (gives you the lat/lon and lets you fan out into other endpoints).", "operationId": "get_circuit_v1_circuits__slug__get", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CircuitDetailOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/states/in": { "get": { "tags": [ "data" ], "summary": "The 36 Indian states + union territories with admin metadata", "description": "Returns ISO-3166-2 state_code, state_name, capital, type (state | union_territory), region (cardinal), population, area_km2, and Wikidata QID. Optional region/type filters.", "operationId": "list_in_states_v1_states_in_get", "parameters": [ { "name": "region", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region" } }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StateOut" }, "title": "Response List In States V1 States In Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/sentiment/{city_id}": { "get": { "tags": [ "data" ], "summary": "Aggregated traveler sentiment per category — Starter+ tier", "description": "Returns avg_rating, review_count, positive/negative %, common_praise + common_complaints keyword arrays per category (overall, hotels, restaurants where available). Megacity rollup applies. Free tier returns 403.", "operationId": "get_city_sentiment_v1_sentiment__city_id__get", "parameters": [ { "name": "city_id", "in": "path", "required": true, "schema": { "type": "string", "title": "City Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/airports/{icao}/weather": { "get": { "tags": [ "data" ], "summary": "Current METAR + TAF forecast + static airport info for an ICAO airport", "description": "Returns NOAA Aviation Weather Center data for one airport: current observation (METAR — temp, wind, visibility, ceiling, flight category VFR/MVFR/IFR/LIFR), forecast (TAF, broken into change periods covering ~24h forward), and static metadata (IATA/FAA ids, runways, elevation, tower frequencies). Use `mode=current` for METAR only, `mode=forecast` for TAF only, default `mode=both` returns all three. Cached 10 min in-process. License: PD-US (NOAA, public domain). Attribution: 'Source: NOAA Aviation Weather Center.'", "operationId": "get_airport_weather_endpoint_v1_airports__icao__weather_get", "parameters": [ { "name": "icao", "in": "path", "required": true, "schema": { "type": "string", "title": "Icao" } }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "default": "both", "title": "Mode" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/exchange": { "get": { "tags": [ "data" ], "summary": "Currency conversion using ECB reference rates", "description": "Convert an amount between currencies using European Central Bank daily reference rates. Optional `date` (YYYY-MM-DD) for historical rates; defaults to latest. License: PD-ECB. 12-hour in-process cache.", "operationId": "exchange_endpoint_v1_exchange_get", "parameters": [ { "name": "amount", "in": "query", "required": true, "schema": { "type": "number", "title": "Amount" } }, { "name": "from_", "in": "query", "required": true, "schema": { "type": "string", "title": "From " } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "title": "To" } }, { "name": "date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/holidays/{country_iso2}/{year}": { "get": { "tags": [ "data" ], "summary": "Public holidays for a country/year (python-holidays library)", "description": "List of public holidays for a country in a given year, with optional sub-national breakdown. Coverage: 200+ countries including **India with 36 state subdivisions** (subdivision='KA' for Karnataka, 'MH' for Maharashtra, etc.). Backed by the BSD-3-licensed `holidays` Python library — in-process lookup, no network hop, no rate limit. The response includes the full list of available subdivisions for the country so the caller can drill in. License: BSD-3-holidays-py.", "operationId": "holidays_endpoint_v1_holidays__country_iso2___year__get", "parameters": [ { "name": "country_iso2", "in": "path", "required": true, "schema": { "type": "string", "title": "Country Iso2" } }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "title": "Year" } }, { "name": "subdivision", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subdivision" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/forecast": { "get": { "tags": [ "data" ], "summary": "Hourly weather forecast for a city_id or any lat/lon (Norwegian Met Institute)", "description": "Hourly forecast for the next 1-36 hours at any point on Earth (not restricted to airports). Returns temperature, humidity, wind, precipitation, cloud cover, plus symbol-code summaries (clear/cloudy/rain/snow/fog/...). Use this for city-grained weather questions; use /v1/airports/{icao}/weather for airport-specific aviation weather. License: CC-BY-4.0 (met.no). 1-hour cache.", "operationId": "forecast_endpoint_v1_forecast_get", "parameters": [ { "name": "lat", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Lat" } }, { "name": "lon", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Lon" } }, { "name": "city_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "default": 24, "title": "Hours" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/local-time": { "get": { "tags": [ "data" ], "summary": "IANA timezone + local clock time for any lat/lon (offline)", "description": "Resolve the IANA timezone for a point on Earth and return the current local clock time (or local time at a specified UTC instant). Fully offline — backed by `timezonefinder` (MIT) + stdlib `zoneinfo` and the IANA tz database. Useful for 'what time is it in ?' and UTC↔local conversions.", "operationId": "local_time_endpoint_v1_local_time_get", "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "title": "Lat" } }, { "name": "lon", "in": "query", "required": true, "schema": { "type": "number", "title": "Lon" } }, { "name": "at", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/countries/{country_iso2}": { "get": { "tags": [ "data" ], "summary": "ISO-3166-1 country info: ISO-3 code, currencies, languages, display name", "description": "Canonical country metadata for an ISO-3166-1 alpha-2 code: ISO-3 code, numeric code, official name, official currency (ISO-4217 via Babel/CLDR), official languages (ISO-639), and a locale-aware display name. Fully offline — pycountry (LGPL) + Babel (BSD-3) ship the underlying data.", "operationId": "country_info_endpoint_v1_countries__country_iso2__get", "parameters": [ { "name": "country_iso2", "in": "path", "required": true, "schema": { "type": "string", "title": "Country Iso2" } }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "default": "en", "title": "Locale" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/calendar/convert": { "get": { "tags": [ "data" ], "summary": "Convert dates across Gregorian/Julian/Hijri/Hebrew/Saka/Jalali/Bahá'í", "description": "Convert a date between civil calendars. Gregorian, Julian, Islamic (arithmetic/tabular Hijri), Hebrew, Indian Civil (Saka), Persian (Jalali), Bahá'í are all supported. The Islamic conversion is arithmetic — observed/sighted Hijri may differ ±1 day; the response flags this. License: MIT (convertdate).", "operationId": "calendar_convert_endpoint_v1_calendar_convert_get", "parameters": [ { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "title": "Date" } }, { "name": "from_calendar", "in": "query", "required": true, "schema": { "type": "string", "title": "From Calendar" } }, { "name": "to_calendar", "in": "query", "required": true, "schema": { "type": "string", "title": "To Calendar" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agent/concierge": { "post": { "tags": [ "agent" ], "summary": "Natural-language travel concierge — grounded itineraries with citations", "description": "Send a natural-language travel query (any language script) and receive a structured, citation-bearing itinerary grounded in TravelMindsAI's data layer. The agent calls internal data tools (cities, circuits, heritage, restaurants, hotels, UNESCO) and composes a day-by-day plan. Counts as 1 quota call plus per-tool sub-calls.", "operationId": "concierge_v1_agent_concierge_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConciergeOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/newsletter/subscribe": { "post": { "tags": [ "public" ], "summary": "Subscribe to the monthly Coverage Flywheel newsletter", "description": "Public endpoint — accepts an email + optional UTM tags. Sends a double-opt-in confirmation email; the row stays unconfirmed until the user clicks the link. GDPR-compliant double-opt-in flow.", "operationId": "newsletter_subscribe_v1_newsletter_subscribe_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterSubscribeBody" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/newsletter/confirm": { "get": { "tags": [ "public" ], "summary": "Consume a newsletter double-opt-in confirmation token", "operationId": "newsletter_confirm_v1_newsletter_confirm_get", "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/partners/inquiry": { "post": { "tags": [ "public" ], "summary": "Submit a partner-program inquiry", "description": "Public endpoint backing the /partners signup form. Records the inquiry in tmai_partner_inquiries and emails the founder.", "operationId": "partners_inquiry_v1_partners_inquiry_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerInquiryBody" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agent/concierge-public": { "post": { "tags": [ "public" ], "summary": "Public Concierge demo — no API key, IP rate-limited", "description": "Lower-friction Concierge path for the marketing playground at travelminds.ai/app/console and /demo/. No authentication required. Rate-limited at 10 calls per IP per hour. Queries are logged for moderation review and may be filtered. Use /v1/agent/concierge with an API key for production traffic. Pass ?stream=1 (or Accept: text/event-stream) to receive SSE events: `started`, `tool_call`, `tool_result`, `thinking` (2s keepalive), and a final `done` event carrying the full ConciergeOut JSON.", "operationId": "concierge_public_v1_agent_concierge_public_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConciergeOut" } } } } } } }, "/v1/agent/tool/{name}": { "post": { "tags": [ "agent" ], "summary": "Direct invocation of any single Concierge tool by name", "description": "Atomic per-tool entry point — bypasses the ReAct loop and just runs one tool against the same Postgres pool the agent uses. Body matches the tool's input_schema (see GET /v1/agent/tools for the registry). Same auth / quota / rate-limits as the data API. One call = one quota.", "operationId": "concierge_subtool_v1_agent_tool__name__post", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "title": "Name" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Concierge Subtool V1 Agent Tool Name Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agent/tools": { "get": { "tags": [ "agent" ], "summary": "List all Concierge sub-tools and their input schemas", "description": "Public registry view. Each entry has name, description, and input_schema (JSON Schema, same shape Anthropic's tool API expects). Drives client-side SDK generation and the /docs/api/concierge.md atomic-tool-endpoints section.", "operationId": "list_concierge_tools_v1_agent_tools_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Response List Concierge Tools V1 Agent Tools Get" } } } } } } }, "/v1/snapshots": { "get": { "tags": [ "data" ], "summary": "Quarterly Parquet snapshot manifest — Growth+ tier", "description": "Returns the latest snapshot_id, generated_at, base_url, and a tables map per Parquet file (count, columns, license note). Free / Starter tiers return 403; Growth and Enterprise can read and download from base_url + filename.", "operationId": "list_snapshots_v1_snapshots_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/heritage/in": { "get": { "tags": [ "data" ], "summary": "ASI Centrally Protected Monuments — 4,312 rows", "description": "All 4,312 ASI-protected monuments. Linked to nearest_city_id where possible. Filterable by state_code (ISO-3166-2 like 'IN-BR') and nearest_city_id. Ordered by distance from nearest city (closest first).", "operationId": "list_in_heritage_v1_heritage_in_get", "parameters": [ { "name": "state_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State Code" } }, { "name": "nearest_city_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nearest City Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-rapidapi-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-Proxy-Secret" } }, { "name": "x-rapidapi-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Rapidapi-User" } }, { "name": "x-tmai-proxy-secret", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Secret" } }, { "name": "x-tmai-proxy-provider", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-Provider" } }, { "name": "x-tmai-proxy-user", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tmai-Proxy-User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HeritageMonumentOut" }, "title": "Response List In Heritage V1 Heritage In Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/webhooks/paddle": { "post": { "tags": [ "webhooks" ], "summary": "Paddle webhook receiver — HMAC-SHA256 verified, persists raw events", "description": "Verifies the Paddle-Signature header (HMAC-SHA256 of `:` with PADDLE_WEBHOOK_SECRET), then persists the raw event into tmai_payment_events. The reconciler worker reads from there and maps events to tmai_subscriptions state.", "operationId": "paddle_webhook_webhooks_paddle_post", "parameters": [ { "name": "Paddle-Signature", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Paddle-Signature" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/webhooks/razorpay": { "post": { "tags": [ "webhooks" ], "summary": "Razorpay webhook receiver — HMAC-SHA256 verified, persists raw events", "description": "Verifies the X-Razorpay-Signature header (HMAC-SHA256 of body with RAZORPAY_WEBHOOK_SECRET), then persists the raw event into tmai_payment_events. The reconciler worker maps events to tmai_subscriptions state.", "operationId": "razorpay_webhook_webhooks_razorpay_post", "parameters": [ { "name": "X-Razorpay-Signature", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Razorpay-Signature" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/webhooks/resend/inbound": { "post": { "tags": [ "webhooks" ], "summary": "Resend inbound webhook — Svix-verified; routes replies to prospect_replies", "description": "Verifies svix-id / svix-timestamp / svix-signature headers against RESEND_INBOUND_SECRET, persists the raw event, then matches the inbound's In-Reply-To header against prospect_touches.resend_message_id to insert a prospect_replies row (classification='unclassified'). The async reply_classifier picks it up on next tick; on 'unsubscribe' it flips prospects.do_not_contact.", "operationId": "resend_inbound_webhook_webhooks_resend_inbound_post", "parameters": [ { "name": "svix-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Svix-Id" } }, { "name": "svix-timestamp", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Svix-Timestamp" } }, { "name": "svix-signature", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Svix-Signature" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "AccountView": { "properties": { "account": { "additionalProperties": true, "type": "object", "title": "Account" }, "plan_id": { "type": "string", "title": "Plan Id" }, "subscription": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Subscription" }, "usage_this_month": { "$ref": "#/components/schemas/UsageView" } }, "type": "object", "required": [ "account", "plan_id", "usage_this_month" ], "title": "AccountView" }, "ApiKeyCreate": { "properties": { "name": { "type": "string", "title": "Name", "default": "default" } }, "type": "object", "title": "ApiKeyCreate" }, "ApiKeyCreateResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "key_prefix": { "type": "string", "title": "Key Prefix" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Revoked At" }, "api_key": { "type": "string", "title": "Api Key" } }, "type": "object", "required": [ "id", "key_prefix", "api_key" ], "title": "ApiKeyCreateResponse" }, "ApiKeyOut": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "key_prefix": { "type": "string", "title": "Key Prefix" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Revoked At" } }, "type": "object", "required": [ "id", "key_prefix" ], "title": "ApiKeyOut" }, "Body_post_draft_edit_dashboard_sdr_drafts__draft_id__edit_post": { "properties": { "body": { "type": "string", "title": "Body" } }, "type": "object", "required": [ "body" ], "title": "Body_post_draft_edit_dashboard_sdr_drafts__draft_id__edit_post" }, "Body_post_feedback_dashboard_sdr_feedback_post": { "properties": { "prospect_id": { "type": "string", "title": "Prospect Id" }, "kind": { "type": "string", "title": "Kind" } }, "type": "object", "required": [ "prospect_id", "kind" ], "title": "Body_post_feedback_dashboard_sdr_feedback_post" }, "Body_post_status_dashboard_sdr_status_post": { "properties": { "prospect_id": { "type": "string", "title": "Prospect Id" }, "new_status": { "type": "string", "title": "New Status" } }, "type": "object", "required": [ "prospect_id", "new_status" ], "title": "Body_post_status_dashboard_sdr_status_post" }, "Body_sva_queue_edit_dashboard_sva_queue_edit_post": { "properties": { "date": { "type": "string", "title": "Date" }, "platform": { "type": "string", "title": "Platform" }, "time": { "type": "string", "title": "Time" }, "body": { "type": "string", "title": "Body" } }, "type": "object", "required": [ "date", "platform", "time", "body" ], "title": "Body_sva_queue_edit_dashboard_sva_queue_edit_post" }, "Body_sva_queue_skip_dashboard_sva_queue_skip_post": { "properties": { "date": { "type": "string", "title": "Date" }, "platform": { "type": "string", "title": "Platform" }, "time": { "type": "string", "title": "Time" } }, "type": "object", "required": [ "date", "platform", "time" ], "title": "Body_sva_queue_skip_dashboard_sva_queue_skip_post" }, "CheckoutBody": { "properties": { "plan_id": { "type": "string", "pattern": "^(starter|growth|scale|enterprise)$", "title": "Plan Id" }, "billing_cycle": { "type": "string", "pattern": "^(monthly|annual)$", "title": "Billing Cycle", "default": "monthly" } }, "type": "object", "required": [ "plan_id" ], "title": "CheckoutBody" }, "CheckoutResponse": { "properties": { "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "transaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transaction Id" }, "subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subscription Id" }, "contact_sales": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Contact Sales" } }, "type": "object", "title": "CheckoutResponse" }, "CircuitDetailOut": { "properties": { "slug": { "type": "string", "title": "Slug" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "ideal_duration_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Ideal Duration Days" }, "best_season": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Best Season" }, "members": { "items": { "$ref": "#/components/schemas/CircuitMemberOut" }, "type": "array", "title": "Members" } }, "type": "object", "required": [ "slug", "name", "members" ], "title": "CircuitDetailOut" }, "CircuitMemberOut": { "properties": { "sequence_no": { "type": "integer", "title": "Sequence No" }, "city_name": { "type": "string", "title": "City Name" }, "state_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State Code" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "city_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City Id" }, "latitude": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latitude" }, "longitude": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Longitude" } }, "type": "object", "required": [ "sequence_no", "city_name" ], "title": "CircuitMemberOut" }, "CircuitOut": { "properties": { "slug": { "type": "string", "title": "Slug", "description": "Kebab-case circuit identifier (e.g. 'buddhist-circuit')." }, "name": { "type": "string", "title": "Name", "description": "Human-readable circuit name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "One-paragraph circuit description." }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "description": "Theme (e.g. 'spiritual', 'heritage', 'eco')." }, "ideal_duration_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Ideal Duration Days", "description": "Recommended trip length in days." }, "best_season": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Best Season", "description": "Best season window (free-form)." }, "states": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "States", "description": "ISO-3166-2 state codes the circuit traverses." }, "cross_border": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Cross Border", "description": "True if the circuit crosses an international border." }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License id from the registry." }, "license_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License Url", "description": "Public URL of the license text." }, "attribution_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Attribution Required", "description": "True if downstream use must cite the upstream source." } }, "type": "object", "required": [ "slug", "name" ], "title": "CircuitOut" }, "CitationsBlock": { "properties": { "tool_calls": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Tool Calls", "default": [] }, "data_sources": { "items": { "type": "string" }, "type": "array", "title": "Data Sources", "default": [] }, "attribution_lines": { "items": { "type": "string" }, "type": "array", "title": "Attribution Lines", "default": [] }, "ground_truth_refs": { "items": { "type": "string" }, "type": "array", "title": "Ground Truth Refs", "default": [] } }, "type": "object", "title": "CitationsBlock" }, "CityOut": { "properties": { "id": { "type": "string", "title": "Id", "description": "Canonical city UUID. Stable across reads." }, "name": { "type": "string", "title": "Name", "description": "City name in source script (en preferred when both exist)." }, "iso_alpha2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso Alpha2", "description": "ISO-3166 alpha-2 country code, uppercase (e.g. 'IN', 'JP')." }, "population": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Population", "description": "Latest known population from source metadata." }, "latitude": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latitude", "description": "Decimal degrees, signed (string for arbitrary precision)." }, "longitude": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Longitude", "description": "Decimal degrees, signed (string for arbitrary precision)." }, "master_score": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Master Score", "description": "Composite TMAIV2 master score, rounded to 2dp. Range 0-1." }, "tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tier", "description": "Internal classification tier (e.g. 'tier-1', 'tier-2')." }, "child_city_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Child City Count", "description": "Number of child neighborhoods/boroughs aggregated under this row (W52 rollup)." }, "aggregates_neighborhoods": { "type": "boolean", "title": "Aggregates Neighborhoods", "description": "True when this is a megacity row that rolls up child neighborhoods (NYC, London, Paris, Tokyo).", "default": false }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License id from the registry (D7 posture). See GET /v1/licenses." }, "license_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License Url", "description": "Public URL of the license text." }, "attribution_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Attribution Required", "description": "True if downstream use must cite TravelMindsAI / the upstream source." } }, "type": "object", "required": [ "id", "name" ], "title": "CityOut" }, "CityRef": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "name": { "type": "string", "title": "Name" }, "iso_alpha2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso Alpha2" }, "state_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State Code" } }, "type": "object", "required": [ "name" ], "title": "CityRef" }, "ConciergeOut": { "properties": { "version": { "type": "string", "title": "Version", "default": "concierge_v0" }, "query": { "type": "string", "title": "Query" }, "language_detected": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language Detected" }, "summary": { "type": "string", "title": "Summary", "default": "" }, "itinerary": { "items": { "$ref": "#/components/schemas/ItineraryDay" }, "type": "array", "title": "Itinerary", "default": [] }, "restaurants_recommended": { "items": { "$ref": "#/components/schemas/RestaurantRecommended" }, "type": "array", "title": "Restaurants Recommended", "default": [] }, "heritage_highlights": { "items": { "$ref": "#/components/schemas/HeritageHighlight" }, "type": "array", "title": "Heritage Highlights", "default": [] }, "coverage_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Coverage Notes" }, "citations": { "$ref": "#/components/schemas/CitationsBlock", "default": { "tool_calls": [], "data_sources": [], "attribution_lines": [], "ground_truth_refs": [] } }, "partial": { "type": "boolean", "title": "Partial", "default": false }, "degraded_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Degraded Reason" }, "tokens_used": { "$ref": "#/components/schemas/TokensUsed", "default": { "input": 0, "output": 0, "cache_read": 0, "cache_create": 0 } }, "tool_calls_made": { "type": "integer", "title": "Tool Calls Made", "default": 0 }, "elapsed_ms": { "type": "integer", "title": "Elapsed Ms", "default": 0 }, "layout_hint": { "type": "string", "title": "Layout Hint", "default": "universal" } }, "type": "object", "required": [ "query" ], "title": "ConciergeOut" }, "ForgotPasswordBody": { "properties": { "email": { "type": "string", "format": "email", "title": "Email" } }, "type": "object", "required": [ "email" ], "title": "ForgotPasswordBody" }, "ForgotPasswordResponse": { "properties": { "sent": { "type": "boolean", "title": "Sent", "default": true } }, "type": "object", "title": "ForgotPasswordResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HealthResponse": { "properties": { "ok": { "type": "boolean", "title": "Ok", "default": true }, "service": { "type": "string", "title": "Service", "default": "tmaiv2-gateway" }, "version": { "type": "string", "title": "Version", "default": "0.6.0" } }, "type": "object", "title": "HealthResponse" }, "HeritageHighlight": { "properties": { "name": { "type": "string", "title": "Name" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "citation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Citation" } }, "type": "object", "required": [ "name" ], "title": "HeritageHighlight" }, "HeritageMonumentOut": { "properties": { "id": { "type": "string", "title": "Id", "description": "Monument UUID (ASI Centrally Protected Monuments)." }, "name": { "type": "string", "title": "Name", "description": "Monument name as published by the ASI." }, "state_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State Code", "description": "ISO-3166-2 state code (e.g. 'IN-BR')." }, "district_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "District Name", "description": "District name as published." }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "description": "Heritage category (e.g. 'temple', 'fort', 'tomb')." }, "protected_since": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Protected Since", "description": "Year the monument was first protected by the ASI." }, "latitude": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latitude", "description": "Decimal degrees, signed." }, "longitude": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Longitude", "description": "Decimal degrees, signed." }, "nearest_city_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nearest City Id", "description": "Canonical UUID of the nearest TMAIV2-tracked city." }, "nearest_city_km": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nearest City Km", "description": "Crow-fly distance to nearest_city_id in km." }, "wikidata_qid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wikidata Qid", "description": "Wikidata QID if grounded." }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License id (typically 'CC-BY-4.0' for ASI publications)." }, "license_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License Url", "description": "Public URL of the license text." }, "attribution_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Attribution Required", "description": "True if downstream use must cite the ASI." } }, "type": "object", "required": [ "id", "name" ], "title": "HeritageMonumentOut" }, "ItineraryDay": { "properties": { "day": { "type": "integer", "title": "Day" }, "city": { "anyOf": [ { "$ref": "#/components/schemas/CityRef" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "morning": { "items": { "$ref": "#/components/schemas/ItineraryItem" }, "type": "array", "title": "Morning", "default": [] }, "afternoon": { "items": { "$ref": "#/components/schemas/ItineraryItem" }, "type": "array", "title": "Afternoon", "default": [] }, "evening": { "items": { "$ref": "#/components/schemas/ItineraryItem" }, "type": "array", "title": "Evening", "default": [] }, "items": { "items": { "$ref": "#/components/schemas/ItineraryItem" }, "type": "array", "title": "Items", "default": [] }, "stay": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Stay" }, "transit_in": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Transit In" } }, "type": "object", "required": [ "day" ], "title": "ItineraryDay" }, "ItineraryItem": { "properties": { "item": { "type": "string", "title": "Item" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "duration_min": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Min" }, "citation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Citation" } }, "type": "object", "required": [ "item" ], "title": "ItineraryItem" }, "LodgingOut": { "properties": { "id": { "type": "string", "title": "Id", "description": "Canonical hotel / restaurant / experience UUID." }, "name": { "type": "string", "title": "Name", "description": "Venue name." }, "city_id": { "type": "string", "title": "City Id", "description": "Parent city UUID. Megacity rollup applies on city_id queries." }, "city_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City Name", "description": "Parent city name (denormalised)." }, "iso_alpha2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso Alpha2", "description": "Country code of the parent city." }, "rating": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rating", "description": "Source-provided rating (string-typed; precision varies)." }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Upstream data source (e.g. 'michelin', 'booking', 'foursquare')." }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License id from the registry." }, "license_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License Url", "description": "Public URL of the license text." }, "attribution_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Attribution Required", "description": "True if downstream use must cite the upstream source." } }, "type": "object", "required": [ "id", "name", "city_id" ], "title": "LodgingOut" }, "LoginBody": { "properties": { "email": { "type": "string", "format": "email", "title": "Email" }, "password": { "type": "string", "title": "Password" } }, "type": "object", "required": [ "email", "password" ], "title": "LoginBody" }, "MeResponse": { "properties": { "account_id": { "type": "string", "title": "Account Id" }, "plan_id": { "type": "string", "title": "Plan Id" }, "subscription_status": { "type": "string", "title": "Subscription Status" }, "quota": { "type": "integer", "title": "Quota" }, "used": { "type": "integer", "title": "Used" }, "remaining": { "type": "integer", "title": "Remaining" }, "concierge_quota": { "type": "integer", "title": "Concierge Quota", "default": 0 }, "concierge_used": { "type": "integer", "title": "Concierge Used", "default": 0 }, "concierge_remaining": { "type": "integer", "title": "Concierge Remaining", "default": 0 }, "rate_limit_per_minute": { "type": "integer", "title": "Rate Limit Per Minute" } }, "type": "object", "required": [ "account_id", "plan_id", "subscription_status", "quota", "used", "remaining", "rate_limit_per_minute" ], "title": "MeResponse" }, "NarrativeOut": { "properties": { "section": { "type": "string", "title": "Section", "description": "Narrative section slug (e.g. 'overview', 'food', 'getting-around')." }, "content": { "type": "string", "title": "Content", "description": "The narrative body. Hallucination-checked (W9 v2 multilingual)." }, "word_count": { "type": "integer", "title": "Word Count", "description": "Word count of the content body." }, "model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Name", "description": "LLM that generated the narrative (e.g. 'qwen/qwen3-30b-a3b-2507')." }, "model_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Version", "description": "Model version / prompt-version stamp." }, "generated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Generated At", "description": "UTC timestamp of generation." } }, "type": "object", "required": [ "section", "content", "word_count" ], "title": "NarrativeOut" }, "NewsletterSubscribeBody": { "properties": { "email": { "type": "string", "maxLength": 254, "minLength": 4, "title": "Email" }, "source_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Path" }, "utm_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Source" }, "utm_medium": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Medium" }, "utm_campaign": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Campaign" } }, "type": "object", "required": [ "email" ], "title": "NewsletterSubscribeBody" }, "OnboardingEventBody": { "properties": { "event": { "type": "string", "pattern": "^(api_key_created|first_call|concierge_tried|docs_read)$", "title": "Event" }, "payload": { "additionalProperties": true, "type": "object", "title": "Payload" } }, "type": "object", "required": [ "event" ], "title": "OnboardingEventBody" }, "POIOut": { "properties": { "id": { "type": "string", "title": "Id", "description": "Canonical POI UUID." }, "name": { "type": "string", "title": "Name", "description": "POI name in source script." }, "city_id": { "type": "string", "title": "City Id", "description": "Parent city UUID. Megacity rollup applies on city_id queries." }, "city_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City Name", "description": "Parent city name (denormalised for convenience)." }, "iso_alpha2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso Alpha2", "description": "Country code of the parent city." }, "rating": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rating", "description": "Source-provided rating (string-typed; precision varies by source)." }, "fsq_categories": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fsq Categories", "description": "Raw upstream category labels. **Deprecated 2026-07-21** — switch to `category_normalized`." }, "category_normalized": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Category Normalized", "description": "Ordered, deduplicated list of in-house category slugs (e.g. ['do.beach', 'eat.cafe']). First element is the primary category. ~64 leaves across 8 domains (eat / sleep / see / do / shop / move / live / geo). See https://travelminds.ai/docs/category-normalized for the full taxonomy." }, "wikidata_qid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wikidata Qid", "description": "Wikidata QID (e.g. 'Q243') if the POI is grounded." }, "wikipedia_en": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wikipedia En", "description": "English Wikipedia article slug if known." }, "wikidata_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wikidata Label", "description": "Wikidata label used for matching." }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Upstream data source (e.g. 'foursquare', 'osm', 'wikidata')." }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License id from the registry (D7 posture)." }, "license_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License Url", "description": "Public URL of the license text." }, "attribution_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Attribution Required", "description": "True if downstream use must cite the upstream source." } }, "type": "object", "required": [ "id", "name", "city_id" ], "title": "POIOut" }, "PartnerInquiryBody": { "properties": { "name": { "type": "string", "maxLength": 120, "minLength": 2, "title": "Name" }, "email": { "type": "string", "maxLength": 254, "minLength": 4, "title": "Email" }, "company": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Company" }, "partner_type": { "type": "string", "pattern": "^(agency|academic|integration|other)$", "title": "Partner Type" }, "description": { "type": "string", "maxLength": 4000, "minLength": 10, "title": "Description" }, "expected_volume": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Expected Volume" } }, "type": "object", "required": [ "name", "email", "partner_type", "description" ], "title": "PartnerInquiryBody" }, "PlanOut": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "monthly_request_quota": { "type": "integer", "title": "Monthly Request Quota" }, "monthly_concierge_quota": { "type": "integer", "title": "Monthly Concierge Quota", "default": 0 }, "rate_limit_per_minute": { "type": "integer", "title": "Rate Limit Per Minute" }, "price_usd_monthly": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Price Usd Monthly" }, "price_usd_annual": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Price Usd Annual" }, "price_inr_monthly": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Price Inr Monthly" }, "price_inr_annual": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Price Inr Annual" }, "features": { "additionalProperties": true, "type": "object", "title": "Features", "default": {} } }, "type": "object", "required": [ "id", "name", "monthly_request_quota", "rate_limit_per_minute" ], "title": "PlanOut" }, "RefreshBody": { "properties": { "refresh_token": { "type": "string", "title": "Refresh Token" } }, "type": "object", "required": [ "refresh_token" ], "title": "RefreshBody" }, "ResetPasswordBody": { "properties": { "token": { "type": "string", "title": "Token" }, "new_password": { "type": "string", "maxLength": 128, "minLength": 10, "title": "New Password" } }, "type": "object", "required": [ "token", "new_password" ], "title": "ResetPasswordBody" }, "ResetPasswordResponse": { "properties": { "reset": { "type": "boolean", "title": "Reset", "default": true }, "email": { "type": "string", "title": "Email" } }, "type": "object", "required": [ "email" ], "title": "ResetPasswordResponse" }, "RestaurantRecommended": { "properties": { "city_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City Id" }, "name": { "type": "string", "title": "Name" }, "michelin_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Michelin Tier" }, "citation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Citation" } }, "type": "object", "required": [ "name" ], "title": "RestaurantRecommended" }, "RevokeResponse": { "properties": { "revoked": { "type": "string", "title": "Revoked" } }, "type": "object", "required": [ "revoked" ], "title": "RevokeResponse" }, "ScoreOut": { "properties": { "city_id": { "type": "string", "title": "City Id", "description": "City UUID this score row applies to." }, "name": { "type": "string", "title": "Name", "description": "City name." }, "iso_alpha2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso Alpha2", "description": "Country code." }, "master_score": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Master Score", "description": "Composite master score (0-1, 2dp)." }, "tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tier", "description": "Internal tier classification." }, "social_sub": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Social Sub", "description": "Social/travel-buzz sub-score." }, "connectivity_sub": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connectivity Sub", "description": "Connectivity (air/rail/road) sub-score." }, "nps_sub": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nps Sub", "description": "Net-promoter style sub-score from review aggregates." }, "value_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value Index", "description": "Cost-vs-quality value index." }, "dimensions_scored": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Dimensions Scored", "description": "Number of input dimensions used to compute this score." }, "rising_star": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rising Star", "description": "Rising-star momentum signal." }, "family_travel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Family Travel", "description": "Family-travel suitability index." }, "luxury_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Luxury Index", "description": "Luxury-travel suitability index." }, "adventure_travel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Adventure Travel", "description": "Adventure-travel suitability index." }, "retirement_expat": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retirement Expat", "description": "Retirement / long-term expat suitability." }, "weekend_getaway": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Weekend Getaway", "description": "Short-trip / weekend-getaway suitability." }, "overtourism_risk": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Overtourism Risk", "description": "Overtourism risk index (higher = more crowded)." }, "best_fit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Best Fit", "description": "Best-fit traveler-persona label (free-form short string)." }, "indices_scored": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Indices Scored", "description": "Number of derived indices populated for this row." } }, "type": "object", "required": [ "city_id", "name" ], "title": "ScoreOut" }, "SignupBody": { "properties": { "email": { "type": "string", "format": "email", "title": "Email" }, "password": { "type": "string", "maxLength": 128, "minLength": 10, "title": "Password" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "organisation_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organisation Name" }, "billing_country": { "type": "string", "maxLength": 2, "minLength": 2, "title": "Billing Country" }, "signup_plan_intent": { "anyOf": [ { "type": "string", "maxLength": 24 }, { "type": "null" } ], "title": "Signup Plan Intent" }, "signup_cycle_intent": { "anyOf": [ { "type": "string", "maxLength": 12 }, { "type": "null" } ], "title": "Signup Cycle Intent" } }, "type": "object", "required": [ "email", "password", "billing_country" ], "title": "SignupBody" }, "SignupResponse": { "properties": { "account_id": { "type": "string", "title": "Account Id" }, "email": { "type": "string", "title": "Email" }, "email_verification": { "type": "string", "title": "Email Verification", "default": "sent" } }, "type": "object", "required": [ "account_id", "email" ], "title": "SignupResponse" }, "StateOut": { "properties": { "state_code": { "type": "string", "title": "State Code", "description": "ISO-3166-2 state code (e.g. 'IN-BR')." }, "state_name": { "type": "string", "title": "State Name", "description": "Official state name in English." }, "capital": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Capital", "description": "State capital city name." }, "type": { "type": "string", "title": "Type", "description": "'state' or 'union_territory'." }, "region": { "type": "string", "title": "Region", "description": "Cardinal region (north / south / east / west / north-east / central)." }, "population": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Population", "description": "Latest census population." }, "area_km2": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Area Km2", "description": "Area in square kilometres." }, "wikidata_qid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wikidata Qid", "description": "Wikidata QID for the state entity." } }, "type": "object", "required": [ "state_code", "state_name", "type", "region" ], "title": "StateOut" }, "TokenResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token" }, "refresh_token": { "type": "string", "title": "Refresh Token" }, "token_type": { "type": "string", "title": "Token Type", "default": "Bearer" }, "expires_in": { "type": "integer", "title": "Expires In", "default": 3600 }, "account": { "additionalProperties": true, "type": "object", "title": "Account" } }, "type": "object", "required": [ "access_token", "refresh_token", "account" ], "title": "TokenResponse" }, "TokensUsed": { "properties": { "input": { "type": "integer", "title": "Input", "default": 0 }, "output": { "type": "integer", "title": "Output", "default": 0 }, "cache_read": { "type": "integer", "title": "Cache Read", "default": 0 }, "cache_create": { "type": "integer", "title": "Cache Create", "default": 0 } }, "type": "object", "title": "TokensUsed" }, "UNESCOOut": { "properties": { "id": { "type": "string", "title": "Id", "description": "Site UUID." }, "site_name": { "type": "string", "title": "Site Name", "description": "Official UNESCO site name." }, "year_inscribed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Year Inscribed", "description": "Year the site was first inscribed." }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region", "description": "UNESCO region (e.g. 'Asia and the Pacific')." }, "site_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Site Type", "description": "cultural / natural / mixed." }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "inscribed / in_danger / delisted." }, "significance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Significance", "description": "UNESCO statement of outstanding universal value (excerpt)." }, "latitude": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latitude", "description": "Decimal degrees, signed." }, "longitude": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Longitude", "description": "Decimal degrees, signed." }, "country_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country Name", "description": "Country name (English)." }, "iso_alpha2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso Alpha2", "description": "Country ISO-3166 alpha-2 code." }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License id from the registry." }, "license_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License Url", "description": "Public URL of the license text." }, "attribution_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Attribution Required", "description": "True if downstream use must cite UNESCO." } }, "type": "object", "required": [ "id", "site_name" ], "title": "UNESCOOut" }, "UsageView": { "properties": { "request_count": { "type": "integer", "title": "Request Count" }, "bytes_returned": { "type": "integer", "title": "Bytes Returned" }, "quota": { "type": "integer", "title": "Quota" }, "remaining": { "type": "integer", "title": "Remaining" }, "concierge_count": { "type": "integer", "title": "Concierge Count", "default": 0 }, "concierge_quota": { "type": "integer", "title": "Concierge Quota", "default": 0 }, "concierge_remaining": { "type": "integer", "title": "Concierge Remaining", "default": 0 } }, "type": "object", "required": [ "request_count", "bytes_returned", "quota", "remaining" ], "title": "UsageView" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VerifyEmailResponse": { "properties": { "verified": { "type": "boolean", "title": "Verified" }, "account_id": { "type": "string", "title": "Account Id" }, "email": { "type": "string", "title": "Email" } }, "type": "object", "required": [ "verified", "account_id", "email" ], "title": "VerifyEmailResponse" }, "VisaOut": { "properties": { "passport_country": { "type": "string", "title": "Passport Country", "description": "Country of the passport holder." }, "destination_country": { "type": "string", "title": "Destination Country", "description": "Country being travelled to." }, "requirement": { "type": "string", "title": "Requirement", "description": "One of: visa_free, visa_on_arrival, e_visa, visa_required, no_admission." }, "duration_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Days", "description": "Allowed stay in days (visa-free/visa-on-arrival)." }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes", "description": "Free-form caveats from the source (e.g. fee, conditions)." }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "License of this row (registry ID)." }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Source organisation or dataset name." }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Url", "description": "Canonical link back to the upstream." }, "license_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License Url", "description": "Registry URL for this license." }, "attribution_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Attribution Required", "description": "True if downstream consumers must attribute." } }, "type": "object", "required": [ "passport_country", "destination_country", "requirement" ], "title": "VisaOut" }, "WebhookResponse": { "properties": { "received": { "type": "boolean", "title": "Received", "default": true }, "event_type": { "type": "string", "title": "Event Type" }, "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Id" } }, "type": "object", "required": [ "event_type" ], "title": "WebhookResponse" } } }, "tags": [ { "name": "public", "description": "No authentication required." }, { "name": "auth", "description": "Signup, login, email verification, refresh." }, { "name": "account", "description": "Account, API keys, usage. Session-authenticated." }, { "name": "billing", "description": "Hosted checkout via Paddle or Razorpay." }, { "name": "data", "description": "The dataset itself. API-key-authenticated." }, { "name": "webhooks", "description": "Provider event ingestion. Signature-verified." } ], "servers": [ { "url": "https://api.travelminds.ai", "description": "TravelMindsAI production gateway" } ] }