Resolve agent

GET/v1/agents:resolve

The public profile of one agent by handle

Answers the public AgentPublicProfile of a registered agent: its handle, name, operator name and domain, tier, current version, protocols, key thumbprints, A2A card URL, certificate state and a public log of registry events. It never carries the principal, the tenant id or any traffic. A private agent (private true) and an unknown handle are the same 404 NOT_FOUND, so a handle cannot be probed. Anonymous: no credential is needed (security is empty); rate-limited per IP and per key, and an over-limit caller is 429 RATE_LIMITED. 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

handlestringRequired
The agent handle, name@domain: a hosted handle is name@<tenantSlug>.agents.aikonic.travel, an own-domain handle is name@your-domain.

Headers

SignaturestringOptional
RFC 9421 Web Bot Auth: the signature value, labelled to match Signature-Input.Show more
RFC 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 more
RFC 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 more
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 version gives no ANS proof (tier at most T1).

Request body

This operation takes no request body.

Responses

200The agent's public profileAgentPublicProfile
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 more
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; nextAction stop). A request without a signature is never refused here.
ApiErrorResponse
404NOT_FOUND — unknown or expired ref (unguessable refs, 15)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 more
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). 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 more
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). 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 more
RATE_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

Errors you should handle

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

400	VALIDATION message.intent.checkOut must be after message.intent.checkIn	not retryable
400	UNKNOWN_DOMAIN Unknown domain 'HOTELS'. Did you mean HTL?	not retryable
401	UNAUTHENTICATED The Web Bot Auth signature did not verify: created is older than 300 seconds.	not retryable
404	NOT_FOUND searchRef SR-F-7b31d0a9 is unknown or has expired; re-search	not retryable
405	VALIDATION This method is not served.	not retryable
414	VALIDATION The request URI is longer than 8 KiB.	not retryable
429	RATE_LIMITED Too many requests for this key on the supplier budget. Wait for the Retry-After interval before trying again.	retryable
500	INTERNAL An unexpected error occurred. Quote the traceId to support.	retryable