> ## Documentation Index > Fetch the complete documentation index at: https://docs.rail402.dev/llms.txt > Use this file to discover all available pages before exploring further. # Search the catalog > Natural-language search over published listings. Hard filters, from parameters or recognised in the query text, apply before ranking; lexical (BM25F) and semantic (local embeddings) rankings are fused with reciprocal rank fusion. Explicit parameters override the same constraint in the text. ## OpenAPI ````yaml /api-reference/openapi.yaml get /discovery/search openapi: 3.1.0 info: title: Rail402 version: 0.0.0 summary: x402 facilitator and Bazaar discovery layer for Stellar. description: > The Rail402 HTTP service. `/supported`, `/verify` and `/settle` follow the x402 version 2 facilitator interface; `/discovery/*` serves the Bazaar catalog and search. Every endpoint except `/health`, `/ready` and `/metrics` is rate-limited per client address. A limited request gets HTTP 429 with a `Retry-After` header and the code `rate_limited`. license: name: Apache-2.0 identifier: Apache-2.0 servers: - url: https://testnet.rail402.dev description: Hosted testnet facilitator (stellar:testnet only, no API key) security: [] tags: - name: Facilitator description: x402 facilitator interface. - name: Discovery description: Bazaar catalog and natural-language search. - name: Operations description: Health, readiness, metrics and usage. paths: /discovery/search: get: tags: - Discovery summary: Search the catalog description: > Natural-language search over published listings. Hard filters, from parameters or recognised in the query text, apply before ranking; lexical (BM25F) and semantic (local embeddings) rankings are fused with reciprocal rank fusion. Explicit parameters override the same constraint in the text. operationId: searchResources parameters: - name: query in: query required: true description: > What to find, in natural language. 1 to 500 characters after trimming. Longer than 500 after trimming is `search_query_too_long`; longer than 2,000 is `discovery_invalid_parameter`. schema: type: string maxLength: 2000 example: current weather for a city on testnet under 2 cents - $ref: '#/components/parameters/Type' - $ref: '#/components/parameters/PayTo' - $ref: '#/components/parameters/Scheme' - $ref: '#/components/parameters/Network' - $ref: '#/components/parameters/Extensions' - name: asset in: query description: >- Only payment options in this asset, by `C…` contract address or symbol. schema: type: string pattern: ^C[A-Z2-7]{55}$|^[A-Za-z0-9]{1,12}$ - name: maxPrice in: query description: >- Price ceiling, in the asset's units if `asset` is set, else in US dollars. schema: type: string pattern: ^\d{1,15}(\.\d{1,18})?$ - name: limit in: query description: Page size, in resources. Values above 50 are clamped to 50. schema: type: integer minimum: 1 default: 10 - name: cursor in: query description: The `pagination.cursor` of the previous page. schema: type: string maxLength: 512 responses: '200': description: A page of results, best first. content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: > `discovery_invalid_parameter` (missing `query`, malformed or unsupported parameter), `search_query_required`, `search_query_too_long`, `search_invalid_cursor` or `search_cursor_expired`. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: error: code: search_query_required reason: The `query` parameter is required and must not be blank. retryable: false '429': $ref: '#/components/responses/RateLimited' components: parameters: Type: name: type in: query description: Only listings of this resource type. Unknown types match nothing. schema: type: string pattern: ^[a-z][a-z0-9_-]{0,31}$ examples: - http - mcp PayTo: name: payTo in: query description: >- Only payment options paying this address (a `G…` address also matches muxed addresses on it). schema: type: string pattern: ^[A-Z2-7]{56}$|^M[A-Z2-7]{68}$ Scheme: name: scheme in: query description: Only payment options in this scheme. schema: type: string pattern: ^[a-z][a-z0-9_-]{0,31}$ examples: - exact Network: name: network in: query description: Only payment options on this CAIP-2 network. schema: type: string pattern: ^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,64}$ examples: - stellar:testnet Extensions: name: extensions in: query description: >- Comma-separated extension keys (at most 10) every resource must declare in its 402 response. schema: type: string pattern: ^[a-zA-Z0-9_-]{1,64}(,[a-zA-Z0-9_-]{1,64}){0,9}$ examples: - bazaar schemas: SearchResponse: type: object required: - x402Version - resources - partialResults - pagination - rail402 properties: x402Version: type: integer const: 2 resources: type: array items: $ref: '#/components/schemas/DiscoveryItem' partialResults: type: boolean description: >- True when the semantic ranking was cut at its depth, or a ranked (not filter-only) search ran lexical-only because no model is loaded or embedding the query failed or took over 2 seconds. pagination: type: object required: - limit - cursor properties: limit: type: integer cursor: type: - string - 'null' rail402: type: object required: - method - recognised - revision properties: method: type: string enum: - hybrid - lexical - filter recognised: type: array items: type: string examples: - - network=stellar:testnet - maxPrice=0.02 USD revision: type: integer ErrorBody: type: object required: - error properties: error: type: object required: - code - reason - retryable properties: code: type: string reason: type: string retryable: type: boolean details: type: object additionalProperties: true DiscoveryItem: type: object required: - resource - type - x402Version - accepts - lastUpdated - extensions - rail402 properties: resource: type: string type: type: string enum: - http - mcp x402Version: type: integer const: 2 accepts: type: array items: $ref: '#/components/schemas/PaymentRequirements' lastUpdated: type: string format: date-time description: type: string mimeType: type: string serviceName: type: string tags: type: array items: type: string iconUrl: type: string extensions: type: object required: - bazaar description: >- `bazaar`, and an empty object for every other extension the resource declares in its 402 response. properties: bazaar: type: object description: >- The validated `info`, `schema` and, if accepted, `routeTemplate`. additionalProperties: true additionalProperties: type: object maxProperties: 0 rail402: type: object description: >- The catalog listings behind the resource. A resource sold on several networks is one item with one listing per network. required: - trust - settlements - listings - options properties: method: type: string toolName: type: string trust: type: string enum: - settled - origin_verified - domain_verified description: The strongest trust among the resource's listings. settlements: type: integer description: Settlements across the resource's listings. listings: type: array minItems: 1 items: type: object required: - id - network - version - trust - owner - settlements - firstCataloged - lastSettled properties: id: type: string format: uuid network: type: string version: type: integer trust: type: string enum: - settled - origin_verified - domain_verified owner: type: string settlements: type: integer firstCataloged: type: string format: date-time lastSettled: type: string format: date-time stellar: type: object description: >- When the listing's Stellar facts were read; absent until first checked. required: - checkedAt properties: checkedAt: type: string format: date-time domain: type: object required: - host - claimsOwner properties: host: type: string claimsOwner: type: boolean description: >- Whether the host's SEP-1 stellar.toml lists the owner in ACCOUNTS. options: type: array description: One entry per `accepts` option, in the same order. items: type: object required: - listing properties: listing: type: string format: uuid description: The listing the option belongs to. symbol: type: string name: type: string decimals: type: integer receivable: type: boolean description: Whether payTo can receive the token now. PaymentRequirements: type: object description: An x402 version 2 payment option. required: - scheme - network properties: scheme: type: string examples: - exact network: type: string examples: - stellar:testnet asset: type: string description: The SEP-41 token's contract address (`C…`). payTo: type: string description: The recipient, a `G…`, `C…` or `M…` address. amount: type: string description: The amount in the asset's base units. maxTimeoutSeconds: type: integer extra: type: object additionalProperties: true properties: areFeesSponsored: type: boolean additionalProperties: true responses: RateLimited: description: Rate limited (`rate_limited`). headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorBody' headers: RetryAfter: description: Seconds until a retry can succeed. schema: type: integer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.