API reference
Endpoints, parameters, and responses generated from the canonical trust8004 OpenAPI contract.
This page is rendered from the same OpenAPI object served by trust8004. Changes to the contract therefore fail the documentation build instead of silently drifting.
Download the canonical OpenAPI JSON →
/api/v1/catalog/agentsList agents from the free catalogFree marketplace-oriented catalog. It supports the same filters and returns the same agent records as the paid search endpoint; it differs only in that it never computes the categoryCounts/metadataReasonCounts facets (those come back empty — use the paid search endpoint for them). Every indexed agent is reachable for free: enumerate the whole catalog with the afterId keyset cursor, passing the id of the last item of the previous page (?afterId=0&limit=100, then ?afterId=<last id>&limit=100), and stop when a page returns fewer than limit items. Cursor pages cost the same at any depth, accept neither sortBy nor sortOrder, and carry no total field — the short page is the end of the walk. The offset parameter still works for shallow browsing but is capped at 10000 because its cost grows with depth; use afterId beyond that. Filter one or more chains with chainIds; request the newest registrations with sortBy=registered&sortOrder=desc. Sorting by reputation or likes is not available on the free catalog: those two sortBy values answer 400 here because each one aggregates the full registry per request, and they remain available on the paid GET /api/v1/agents endpoint; every other documented sortBy value, including x402, works on the catalog. Future revisions may apply a smaller page cap and a summary projection while preserving this URL.
Parameters
searchSearch text. All-digit values ("42") match agent ids and "{chainId}:{agentId}" ("8453:42") matches one agent exactly. Any other text searches agent names and descriptions and must contain searchable characters, be 2 to 200 characters long, and contain at most 12 terms.
chainIdsComma-separated EVM chain ids to filter by, e.g. "8453,56". Omit for all chains.
ownerFilter to agents owned by this EVM address (0x...).
activeSet "true" to return only agents not revoked/deactivated.
offsetNumber of agents to skip, for pagination (default 0). Negative or invalid values are treated as 0.
sortBySort field. "metadataUpdated" uses the last indexed metadata change time with a stable id tie-breaker for pagination.
sortOrderSort direction: "desc" (default) or "asc".
limitMaximum number of agents to return (default 50, currently capped at 100).
afterIdKeyset cursor for full enumeration: return agents whose id is greater than this value, ordered by ascending id. Start at 0 and pass the id of the last item of each page, stopping when a page returns fewer than limit items. The cursor defines its own order, so it cannot be combined with search, sortBy or sortOrder, and its responses carry no total field. Note that sortBy=id, without a cursor, orders by the on-chain agentId instead — a different column.
/api/v1/catalog/agents/{id}Get one agent from the free catalogFree marketplace-oriented agent profile. It currently returns the same representation as the paid detail endpoint; a future revision may reduce it to a stable summary projection.
Parameters
idrequiredComposite agent id "{chainId}:{agentId}", e.g. "8453:42".
/api/v1/chainsList indexed chainsFree discovery endpoint for the chains and ERC-8004 registries indexed by trust8004.
/api/v1/chains/{chainId}Get indexed chain detailsParameters
chainIdrequiredNumeric chain id to inspect.
/api/v1/agentsSearch registered ERC-8004 agentsSearch and list AI agents registered in the ERC-8004 identity registries indexed by trust8004. Supports full-text search, chain and owner filters, and reputation-based sorting.
Parameters
searchSearch text. All-digit values ("42") match agent ids and "{chainId}:{agentId}" ("8453:42") matches one agent exactly. Any other text searches agent names and descriptions and must contain searchable characters, be 2 to 200 characters long, and contain at most 12 terms.
chainIdsComma-separated EVM chain ids to filter by, e.g. "8453,56". Omit for all chains.
ownerFilter to agents owned by this EVM address (0x...).
activeSet "true" to return only agents not revoked/deactivated.
offsetNumber of agents to skip, for pagination (default 0). Negative or invalid values are treated as 0.
sortBySort field. "metadataUpdated" uses the last indexed metadata change time with a stable id tie-breaker for pagination.
sortOrderSort direction: "desc" (default) or "asc".
limitMaximum number of agents to return (default 50, capped at 100). For larger pages use /api/v1/agents/bulk.
afterIdKeyset cursor for full enumeration: return agents whose id is greater than this value, ordered by ascending id. Start at 0 and pass the id of the last item of each page, stopping when a page returns fewer than limit items. The cursor defines its own order, so it cannot be combined with search, sortBy or sortOrder, and its responses carry no total field. Note that sortBy=id, without a cursor, orders by the on-chain agentId instead — a different column.
/api/v1/agents/bulkBulk-list registered ERC-8004 agentsVolume tier of the agent search: identical filters and response shape, but pages of up to 1000 agents per call. Paginate with offset to retrieve the full filtered dataset.
Parameters
searchSearch text. All-digit values ("42") match agent ids and "{chainId}:{agentId}" ("8453:42") matches one agent exactly. Any other text searches agent names and descriptions and must contain searchable characters, be 2 to 200 characters long, and contain at most 12 terms.
chainIdsComma-separated EVM chain ids to filter by, e.g. "8453,56". Omit for all chains.
ownerFilter to agents owned by this EVM address (0x...).
activeSet "true" to return only agents not revoked/deactivated.
offsetNumber of agents to skip, for pagination (default 0). Negative or invalid values are treated as 0.
sortBySort field. "metadataUpdated" uses the last indexed metadata change time with a stable id tie-breaker for pagination.
sortOrderSort direction: "desc" (default) or "asc".
limitMaximum number of agents to return (default 1000, capped at 1000).
afterIdKeyset cursor for full enumeration: return agents whose id is greater than this value, ordered by ascending id. Start at 0 and pass the id of the last item of each page, stopping when a page returns fewer than limit items. The cursor defines its own order, so it cannot be combined with search, sortBy or sortOrder, and its responses carry no total field. Note that sortBy=id, without a cursor, orders by the on-chain agentId instead — a different column.
/api/v1/agents/{id}Get one agent profileFull indexed profile for a single registered agent: identity, owner, registration metadata, endpoints, and status.
Parameters
idrequiredComposite agent id "{chainId}:{agentId}", e.g. "8453:42" for agent 42 on Base.
/api/v1/agents/{id}/scoreGet an agent trust scoreComputed trust score for one agent: 0-100 total, tier (unverified, bronze, silver, gold, platinum, diamond), and a per-dimension breakdown with weights and confidence.
Parameters
idrequiredComposite agent id "{chainId}:{agentId}", e.g. "8453:42". A bare agent id works if chainId is passed as a query parameter.
chainIdEVM chain id of the agent; only needed when {id} is not composite.
refreshSet "true" to force recomputation instead of the cached score.