View a markdown version of this page

SearchPublicRecords - Agent Registry Public Search (Agent Discovery) API Reference

SearchPublicRecords

Searches public records for agents, tools, skills, and other resources. Results combine keyword and semantic ranking and are returned most relevant first. Only the public descriptors of each record are returned.

Request Syntax

POST /records/search HTTP/1.1 Content-type: application/json { "filters": JSON value, "maxResults": number, "nextToken": "string", "query": "string" }

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

filters

A structured filter that narrows the results. Each condition applies an operator to a field: $eq, $ne, or $in. The identifier field also supports $prefix. To combine conditions, use a single $and or $or key whose value is an array of single-condition objects. Conditions can't be nested further.

You can filter on identifier, domain, recordType, descriptorType, provenance, and recordVersion. For example, {"recordType": {"$eq": "AGENT"}} returns only agents.

A filter can have at most 10 conditions. $in takes 1 to 25 values, and each value is a string of 1 to 512 characters. An empty filter ({}) is not valid.

Type: JSON value

Required: No

maxResults

The maximum number of records to return in one page of results. The default is 20.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No

nextToken

The token returned by a previous request to get the next page of results.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No

query

A natural language query that describes what you are looking for. The query is used for both keyword and semantic ranking.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1024.

Required: No

Response Syntax

HTTP/1.1 200 Content-type: application/json { "nextToken": "string", "records": [ { "createdAt": number, "description": "string", "descriptors": { "string" : { "additionalData": { "string" : "DescriptorEntry" }, "data": "string", "source": { "fromUrl": { "url": "string" } }, "version": "string" } }, "displayName": "string", "domain": "string", "identifier": { ... }, "recordType": "string", "recordVersion": "string", "trustManifests": [ { "contributor": "string", "provenance": [ { "relation": "string", "sourceId": "string" } ] } ], "updatedAt": number } ] }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

nextToken

The token to pass in a later request to get the next page of results. This value is absent when there are no more results.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

records

The records that match the search, most relevant first.

Type: Array of PublicRecord objects

Errors

For information about the errors that are common to all actions, see Common Error Types.

InternalServerException

The request failed because of an internal error. Retrying the same request is not likely to succeed.

HTTP Status Code: 500

ThrottlingException

The request was denied because the request rate is too high. Reduce the request rate and try again.

HTTP Status Code: 429

ValidationException

The input fails to satisfy the constraints of the operation.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: