> ## Documentation Index > Fetch the complete documentation index at: https://docs.paywithlocus.com/llms.txt > Use this file to discover all available pages before exploring further. # Plan a multi-provider flight search without dispatching > Feature-gated Locus Travel planning route. It validates the normalized search, applies credential and catalog restrictions, selects eligible providers, and returns the aggregate estimated charge. It does not contact travel providers or burn credits. estimateExact is false when at least one selected provider has a live or otherwise variable price. ## OpenAPI ````yaml /api-reference/openapi.json post /wrapped/credits/locus-travel/flight-search/preview openapi: 3.1.0 info: title: Locus Pro API description: >- Access paid tools, manage prepaid balances, and build usage billing. Send money as exact decimal strings and reuse Idempotency-Key on retries. Management routes require a scoped server key or authorized dashboard session. Sensitive workspace changes require an owner or admin with recent MFA or passkey verification, except where an operation documents a stricter boundary. Interactive agents use MCP OAuth; unattended agents use scoped Agent Connections. Browser widgets use end-user tokens. version: 0.7.0 servers: - url: https://api.paywithlocus.com/api description: Production - url: https://api.stage.paywithlocus.com/api description: Stage — evaluation and integration testing security: - secretKey: [] tags: - name: Authentication description: Email-verified self-serve account creation and dashboard identity - name: Tenants description: Tenant profile, keys, and settings (dashboard session or secret key) - name: Workspace members description: Invite-only human workspace membership and role administration - name: Catalog description: Enable/disable APIs and set markups - name: Custom APIs description: Feature-gated enterprise BYOK providers and schema-backed custom actions - name: End users description: End-user accounts, tokens, and allocations - name: Top-ups description: Locus-hosted checkout top-ups and quotes - name: Ledger description: Burn/top-up history and earnings - name: Webhooks description: Signed events, delivery inspection, and replay - name: Burn description: Metered pay-per-use calls - name: MCP description: Stateless Streamable HTTP transport and MCP tool-result contracts - name: Okibi Identity description: >- Feature-gated Okibi identity verification and scoped native CLI credential bootstrap - name: Widget description: End-user JWT surface; a matching publishable key is optional - name: Agent-native onboarding description: >- Self-registration, human Stripe funding handoff, and restricted account setup for headless agents - name: Hosted Workflows description: >- Tenant-private TypeScript Workflow definitions, immutable versions, bounded runs, artifacts, and recovery - name: Agent connections description: Scoped, expiring, revocable credentials for agent execution - name: Recipes description: >- Search, research, extraction, enrichment, and travel outcomes across providers paths: /wrapped/credits/locus-travel/flight-search/preview: post: tags: - Recipes summary: Plan a multi-provider flight search without dispatching description: >- Feature-gated Locus Travel planning route. It validates the normalized search, applies credential and catalog restrictions, selects eligible providers, and returns the aggregate estimated charge. It does not contact travel providers or burn credits. estimateExact is false when at least one selected provider has a live or otherwise variable price. parameters: - $ref: '#/components/parameters/SessionBindingHeader' - name: X-Locus-End-User in: header required: false schema: $ref: '#/components/schemas/ExternalUserId' description: >- Optional end-user identity for a tenant secret or sandbox key. It must agree with body externalUserId when both are present. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TravelFlightSearchRequest' responses: '200': description: No-dispatch provider plan and aggregate estimate headers: Cache-Control: schema: const: private, no-store content: application/json: schema: $ref: '#/components/schemas/TravelFlightSearchPreview' '400': description: Invalid flight search '401': description: Missing or invalid execution credential '403': description: >- Account, end-user, Agent Connection, or endpoint policy denied access '409': description: >- The planned provider calls exceed maxCredits or another credential-level charge ceiling security: - secretKey: [] - sandboxKey: [] - endUserToken: [] - agentConnection: [] components: parameters: SessionBindingHeader: name: X-Locus-Session-Id in: header required: false schema: type: string minLength: 16 maxLength: 128 pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{15,127}$ description: >- Required only when the end-user JWT carries sid. Send the original high-entropy session value; sid is its SHA-256 fingerprint. Ignored for secret-key authentication. schemas: ExternalUserId: type: string minLength: 1 maxLength: 200 pattern: ^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,199}$ description: >- Case-sensitive immutable ID in the tenant namespace. Prefer an identity-provider subject, not an email address. TravelFlightSearchRequest: type: object additionalProperties: false required: - origin - destination - departureDate properties: origin: type: string minLength: 2 maxLength: 120 description: >- IATA code or place name. Three-letter codes are normalized to uppercase. destination: type: string minLength: 2 maxLength: 120 description: Must differ from origin. departureDate: type: string format: date description: Real calendar date in YYYY-MM-DD form. returnDate: type: string format: date description: Optional return date on or after departureDate. adults: type: integer minimum: 1 maximum: 9 default: 1 children: type: integer minimum: 0 maximum: 8 default: 0 infants: type: integer minimum: 0 maximum: 4 default: 0 description: Cannot exceed adults. Total travelers cannot exceed nine. cabinClass: type: string enum: - economy - premium_economy - business - first default: economy currency: type: string pattern: ^[A-Za-z]{3}$ default: USD optimize: type: array maxItems: 3 uniqueItems: true items: type: string enum: - cost - quality - context description: >- Cost favors fewer inexpensive sources, quality increases depth, and context favors compact agent-readable output. preferredAirlines: type: array maxItems: 20 uniqueItems: true items: type: string minLength: 1 maxLength: 100 excludedAirlines: type: array maxItems: 20 uniqueItems: true items: type: string minLength: 1 maxLength: 100 preferredAirports: type: array maxItems: 20 uniqueItems: true items: type: string minLength: 1 maxLength: 100 excludedAirports: type: array maxItems: 20 uniqueItems: true items: type: string minLength: 1 maxLength: 100 maxStops: type: integer minimum: 0 maximum: 3 minLayoverMinutes: type: integer minimum: 0 maximum: 1440 maxLayoverMinutes: type: integer minimum: 0 maximum: 2880 maxDurationMinutes: type: integer minimum: 30 maximum: 10080 maxPrice: type: number exclusiveMinimum: 0 maximum: 10000000 description: Maximum itinerary price in currency. departAfter: type: string pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$ departBefore: type: string pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$ arriveAfter: type: string pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$ arriveBefore: type: string pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$ maxResults: type: integer minimum: 1 maximum: 50 maxProviders: type: integer minimum: 1 maximum: 11 providers: type: array maxItems: 11 uniqueItems: true items: type: string enum: - aircanada - duffel - stabletravel - almosafer - flightconnections - justfly - kayak_hk - skyscanner - skiplagged - trip - united description: >- Optional explicit provider selection, still narrowed by credential, catalog, availability, and request compatibility. maxCredits: oneOf: - type: string pattern: ^(?:0*[1-9]\d*)(?:\.\d{1,6})?$|^0*\.0*[1-9]\d{0,5}$ - type: number exclusiveMinimum: 0 maximum: 1000000000000 description: >- Aggregate no-dispatch ceiling for all selected child calls, in account credits. externalUserId: $ref: '#/components/schemas/ExternalUserId' attribution: type: object additionalProperties: true description: Optional JSON attribution copied to child calls. description: >- Preferred and excluded values cannot overlap. minLayoverMinutes cannot exceed maxLayoverMinutes. Defaults are selected from optimize when optional depth controls are absent. TravelFlightSearchPreview: type: object additionalProperties: false required: - object - capability - request - providers - eligibleProviders - ineligibleProviders - estimatedCostCredits - estimateExact properties: object: const: locus.travel_flight_search.preview capability: const: travel.flight_search request: $ref: '#/components/schemas/TravelFlightSearchRequest' providers: type: array items: type: object additionalProperties: false required: - providerId - providerName - estimatedCostCredits - priceExact properties: providerId: type: string providerName: type: string estimatedCostCredits: $ref: '#/components/schemas/DecimalString' priceExact: type: boolean estimatedCostUsd: type: number minimum: 0 description: Shown only to secret-key and dashboard principals. eligibleProviders: type: array items: type: object properties: providerId: type: string providerName: type: string required: - providerId - providerName additionalProperties: false ineligibleProviders: type: array items: $ref: '#/components/schemas/TravelIneligibleProvider' estimatedCostCredits: $ref: '#/components/schemas/DecimalString' estimateExact: type: boolean estimatedCostUsd: type: number minimum: 0 description: Shown only to secret-key and dashboard principals. DecimalString: type: string pattern: ^\d+(?:\.\d{1,6})?$ description: >- Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply. TravelIneligibleProvider: type: object additionalProperties: false required: - providerId - providerName - reason properties: providerId: type: string providerName: type: string reason: type: string enum: - credential_scope - provider_disabled - provider_filtered - provider_unavailable - request_unsupported detail: type: string securitySchemes: secretKey: type: http scheme: bearer description: Tenant secret key (lcr_…). Server-side only. sandboxKey: type: http scheme: bearer description: >- Sandbox key (lcrsb_…). Metered calls are simulated: no credits move, no providers are called. No management access. Simulation is served from fixtures for the hosted provider catalog; external-rail providers are not registered with the sandbox interceptor and answer 404. endUserToken: type: http scheme: bearer description: >- 60-3600 second end-user JWT minted via /credits/end-users/{id}/token. If the JWT has sid, send the original session value in X-Locus-Session-Id; sid contains only its SHA-256 fingerprint. Bearer tokens are replayable until expiry; use short TTLs, optional session binding, and Idempotency-Key on operations. agentConnection: type: http scheme: bearer description: >- Scoped lcac_ credential. Tenant-managed Agent Connections authorize only their bound MCP and wrapped execution surfaces. A bootstrap connection for a self-registered agent additionally authorizes the explicit /credits/agent/* self-service routes for its own account; neither form authorizes general tenant management. ````