Skip to content
ApiqDevelopers
API v1.64.0Open console
API referenceidentity

Search agent directory

GET/v1/agents:search

Search the travel agent directory

The travel-only directory: public, non-private agents of T1 or above, paged by an opaque cursor.Show moreThe travel-only directory: public, non-private agents of T1 or above, paged by an opaque cursor. Each entry carries the handle, name, operator, tier, protocols, canHold, capabilities and outcomeScore, and never a principal, a tenant id or traffic. Anonymous (security is empty); rate-limited per IP and per key. Web Bot Auth (RFC 9421 HTTP Message Signatures): a caller may sign the request with the Signature, Signature-Input and Signature-Agent headers, and a registered agent declares its version in Agent-Version, which counts only when it is a covered component of the signature. A request with no signature is not an error: it is served as unverified. A signature that is present and wrong is 401 AGENT_SIGNATURE_INVALID, and a covered Agent-Version that names a REVOKED version is 401 AGENT_VERSION_REVOKED. A signature created more than 300 seconds ago, or more than 30 seconds in the future, is invalid.

Query parameters

  • qstringOptional
    Free text matched against the agent name, handle and capabilities.
  • protocolstringOptional
    Only agents that speak this protocol: mcp, a2a or http.
    • mcp
    • a2a
    • http
  • tierstringOptional
    The lowest tier to list, T1 to T3; the default is T1.
    • T1
    • T2
    • T3
  • canHoldbooleanOptional
    true lists only agents allowed to place holds (commit-lite tools); false lists only read-only agents; omitted lists both.
  • cursorstringOptional
    Opaque cursor from the previous page nextCursor; omit for the first page.
  • limitintegerOptional
    Rows per page, 1 to 50; the default is 20.

Headers

  • SignaturestringOptional
    RFC 9421 Web Bot Auth: the signature value, labelled to match Signature-Input.Show moreRFC 9421 Web Bot Auth: the signature value, labelled to match Signature-Input. Optional: an unsigned request is served as unverified. Present and wrong is 401 AGENT_SIGNATURE_INVALID.
  • Signature-InputstringOptional
    RFC 9421 Web Bot Auth: the covered components and parameters (created, keyid, tag="web-bot-auth").Show moreRFC 9421 Web Bot Auth: the covered components and parameters (created, keyid, tag="web-bot-auth"). The signature must cover @authority or @target-uri, @method, @path and signature-agent, and content-digest on bodies; created may be at most 300 seconds old and 30 seconds in the future.
  • Signature-AgentstringOptional
    Web Bot Auth: the HTTPS URL of the signer, whose key directory is /.well-known/http-message-signatures-directory (200 only, no redirects, cached for at most one hour).
  • Agent-VersionstringOptional
    The version a registered agent runs. It counts only when it is a covered component of the signature (SHIP-feat044 A3); a covered REVOKED version is 401 AGENT_VERSION_REVOKED, and an absent or unknown…Show moreThe version a registered agent runs. It counts only when it is a covered component of the signature (SHIP-feat044 A3); a covered REVOKED version is 401 AGENT_VERSION_REVOKED, and an absent or unknown version gives no ANS proof (tier at most T1).

Request body

This operation takes no request body.

Responses

  • 200One page of directory entriesAgentDirectoryPage
  • 400VALIDATION or UNKNOWN_DOMAINApiErrorResponse
  • 401
    The two 401s of the agent identity chain on a route a caller reaches without a credential: AGENT_SIGNATURE_INVALID and AGENT_VERSION_REVOKED (the covered Agent-Version names a REVOKED version;…Show moreThe two 401s of the agent identity chain on a route a caller reaches without a credential: AGENT_SIGNATURE_INVALID and AGENT_VERSION_REVOKED (the covered Agent-Version names a REVOKED version; nextAction stop). A request without a signature is never refused here.
    ApiErrorResponse
  • 405
    VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show moreVALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
    ApiErrorResponse
  • 414
    VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show moreVALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
    ApiErrorResponse
  • 429
    RATE_LIMITED — the API key or its tenant is over a rate limit; wait for Retry-After, then retry.Show moreRATE_LIMITED — the API key or its tenant is over a rate limit; wait for Retry-After, then retry. Every routed request is counted against two token buckets, the key's and the tenant's (all its keys together): 50 requests a second with a burst of 100 on the standard plan. Every travel verb except polling a search also spends from a supplier budget, per key and per tenant: 10 requests a second with a burst of 20, and a plan may add a daily quota of supplier calls. Answers carry the IETF RateLimit header fields for the tightest bucket consulted (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy); a refusal adds Retry-After and details.scope (KEY or TENANT), details.budget (PLATFORM or SUPPLIER), details.reason (RATE or DAILY_QUOTA), details.tier and details.retryAfterMs. A sandbox may run with the limiter off, in which case none of these headers is sent. A search that is still warming is a different answer with a different meaning (keep polling). with the key-velocity check on, also details.reason VELOCITY_LIMIT, a soft breach of the API key's own scope (components/responses/VelocityLimited), nextAction slow_down.
    ApiErrorResponse
  • 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
  • 501
    NOT_IMPLEMENTED — honest fallback; every production 501 is a capabilities-doc bug.Show moreNOT_IMPLEMENTED — honest fallback; every production 501 is a capabilities-doc bug. Also the order read routes (getOrder, listOrderDocuments, listOrderEvents, searchOrders) on a deployment with no order reader assembled; not retryable.
    ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

400VALIDATION
message.intent.checkOut must be after message.intent.checkIn
not retryable
400UNKNOWN_DOMAIN
Unknown domain 'HOTELS'. Did you mean HTL?
not retryable
401UNAUTHENTICATED
The Web Bot Auth signature did not verify: created is older than 300 seconds.
not retryable
405VALIDATION
This method is not served.
not retryable
414VALIDATION
The request URI is longer than 8 KiB.
not retryable
429RATE_LIMITED
Too many requests for this key on the supplier budget. Wait for the Retry-After interval before trying again.
retryable
500INTERNAL
An unexpected error occurred. Quote the traceId to support.
retryable
501NOT_IMPLEMENTED
seatmap is NOT_APPLICABLE for HTL; GET /v1/capabilities says so
not retryable