# Agents (https://developer.godaddy.com/en/docs/references/rest/ans/agents)

***

title: Agents
description: ''
full: true
\_openapi:
toc:

* depth: 2
  title: Search registered agents
  url: '#search-registered-agents'
* depth: 2
  title: List registered agents
  url: '#list-registered-agents'
* depth: 2
  title: Retrieve agent details
  url: '#retrieve-agent-details'
  structuredData:
  headings:
  * content: Search registered agents
    id: search-registered-agents
  * content: List registered agents
    id: list-registered-agents
  * content: Retrieve agent details
    id: retrieve-agent-details
    contents:
  * content: >-
    Searches registered agents using request-body criteria and returns
    ranked results.
    heading: search-registered-agents
  * content: >-
    Lists registered agents using query parameters and returns a ranked
    collection response. This operation is the canonical follow-up target
    for pagination `links[].href` values.
    heading: list-registered-agents
  * content: >-
    Returns a single registered agent with trust explainability details.
    Search-only ranking scores are not included.
    heading: retrieve-agent-details

***

## POST /v1/ans/search-registered-agents

Search registered agents

Searches registered agents using request-body criteria and returns ranked results.

### Header parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `X-Request-Id` | string <uuid> | no | Optional request identifier propagated across services. |

### Request body (required)

Search parameters

Content-Type: `application/json`

Schema:

- object — Search criteria for agent discovery.
  - `query`: string — Optional search query string. If omitted and no filters are provided, the API returns all agents except `REVOKED` by default. When `statuses` is explicitly provided, the API uses only the provided status values. Max length is 256 characters by default. When `keywordExtraction=true`, max length is 4096 characters.
  - `keywordExtraction`: boolean — When true, extracts keywords from the query text before searching. Increases max query length from 256 to 4096 characters. Requires `query` to be non-empty.
  - `keywordAlgorithm`: string — Keyword extraction algorithm to use when `keywordExtraction=true`.
    - enum: "RAKE", "SIMPLE", "TEXTRANK"
  - `profile`: string — Scoring profile name. Cannot be combined with `scoring.pillarWeights` in the same request.
  - `scoring`: object — Optional scoring overrides for this request.
      - `pillarWeights`: object — Optional per-request pillar weights. Supported keys are `identity` and `integrity` only. Values must be 0..100, and provided values must sum to more than 0. When present, `profile` must not be provided.
          - `identity`: integer
          - `integrity`: integer
      - `thresholds`: object — Optional per-request pillar threshold filters. Supported keys are `identity` and `integrity` only. Values must be 0..100.
          - `identity`: integer
          - `integrity`: integer
  - `pageSize`: integer — Number of results per page (1-100).
  - `pageToken`: string — Opaque token from a previous response `links[].href` relation (`rel=next` or `rel=prev`).
  - `pageTokenDirection`: string — Optional token direction when `pageToken` is set. Only valid when `pageToken` is provided. Requests that send `pageTokenDirection` without `pageToken` return `422 INVALID_REQUEST`.
    - enum: "backward", "forward"
  - `totalRequired`: boolean — When true, include `totalItems` and `totalPages` in the response envelope.
  - `providerIds`: array — Filter by provider IDs.
      - items:
  - `statuses`: array — Filter by lifecycle statuses. When omitted, default behavior excludes `REVOKED`.
      - items:
          - enum: "ACTIVE", "WARNING", "DEPRECATED", "EXPIRED", "REVOKED"
  - `agentDomains`: array — Agent host domain-family filters. Each value matches apex plus subdomains.
      - items:
  - `tags`: array — Filter by endpoint function tags (`endpoints.functions.tags`).
      - items:
  - `protocols`: array — Filter by endpoint protocols.
      - items:
          - enum: "A2A", "ACP", "HTTP-API", "MCP"
  - `transports`: array — Filter by endpoint transports.
      - items:
          - enum: "HTTP", "REST", "SSE", "JSON-RPC", "STREAMABLE-HTTP"
  - `capabilities`: array — Filter by function names (`endpoints.functions.name`).
      - items:

### Responses

**200** — Successful response containing a paged list of registered agents

Content-Type: `*/*`

Schema:

- allOf(object & object) — Paged list of agent search results.

**400** — Malformed request syntax or invalid encoding

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**401** — Authentication info not sent or is invalid

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**403** — Authenticated user is not allowed access

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**415** — Unsupported or missing media type

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**422** — Request validation failed

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**429** — Too many requests - rate limit exceeded

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**500** — Internal server error

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**502** — Bad gateway or failed dependency

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**503** — Service is temporarily unavailable

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**504** — Gateway or dependency timeout

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

## GET /v1/ans/registered-agents

List registered agents

Lists registered agents using query parameters and returns a ranked collection response. This operation is the canonical follow-up target for pagination `links[].href` values.

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `profile` | string | no | Scoring profile name (default: `default`). |
| `query` | string | no | Optional search query string. If omitted and no filters are provided, the API returns all agents except `REVOKED` by default. When `statuses` is explicitly provided, the API uses only the provided status values. Max length is 256 characters by default. When `keywordExtraction=true`, max length is 4096 characters. |
| `keywordExtraction` | boolean | no | When true, extracts keywords from the query text before searching. Increases max query length from 256 to 4096 characters. Requires `query` to be non-empty. |
| `keywordAlgorithm` | string | no | Keyword extraction algorithm to use when `keywordExtraction=true`. |
| `pageSize` | integer | no | Number of results per page (1-100). |
| `pageToken` | string | no | Opaque token from a previous response `links[].href` relation (`rel=next` or `rel=prev`). |
| `pageTokenDirection` | string | no | Optional token direction when `pageToken` is set. Only valid when `pageToken` is provided. Requests that send `pageTokenDirection` without `pageToken` return `422 INVALID_REQUEST`. |
| `totalRequired` | boolean | no | When true, include `totalItems` and `totalPages` in the response envelope. |
| `providerIds` | array | no | Filter by provider IDs. |
| `statuses` | array | no | Filter by lifecycle statuses. When omitted, default behavior excludes `REVOKED`. |
| `agentDomains` | array | no | Agent host domain-family filters. Each value matches apex plus subdomains. |
| `protocols` | array | no | Filter by endpoint protocols. |
| `transports` | array | no | Filter by endpoint transports. |
| `tags` | array | no | Filter by endpoint function tags (`endpoints.functions.tags`). |
| `capabilities` | array | no | Filter by function names (`endpoints.functions.name`). |
| `scoring.pillarWeights.identity` | integer | no | Identity pillar weight override. |
| `scoring.pillarWeights.integrity` | integer | no | Integrity pillar weight override. |
| `scoring.thresholds.identity` | integer | no | Identity pillar threshold filter. |
| `scoring.thresholds.integrity` | integer | no | Integrity pillar threshold filter. |

### Header parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `X-Request-Id` | string <uuid> | no | Optional request identifier propagated across services. |

### Responses

**200** — Successful response containing a paged list of registered agents

Content-Type: `*/*`

Schema:

- allOf(object & object) — Paged list of agent search results.

**400** — Malformed request syntax or invalid encoding

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**401** — Authentication info not sent or is invalid

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**403** — Authenticated user is not allowed access

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**422** — Request validation failed

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**429** — Too many requests - rate limit exceeded

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**500** — Internal server error

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**502** — Bad gateway or failed dependency

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**503** — Service is temporarily unavailable

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**504** — Gateway or dependency timeout

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

## GET /v1/ans/registered-agents/{agentId}

Retrieve agent details

Returns a single registered agent with trust explainability details. Search-only ranking scores are not included.

### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `agentId` | string | yes | Unique agent identifier. |

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `profile` | string | no | Scoring profile name (default: `default`). |

### Header parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `X-Request-Id` | string <uuid> | no | Optional request identifier propagated across services. |

### Responses

**200** — Successful agent detail retrieval

Content-Type: `*/*`

Schema:

- allOf(object & object) — Full agent representation with trust explainability fields.

**400** — Malformed request syntax or invalid encoding

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**401** — Authentication info not sent or is invalid

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**403** — Authenticated user is not allowed access

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**404** — Resource not found

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**422** — Request validation failed

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**429** — Too many requests - rate limit exceeded

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**500** — Internal server error

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**502** — Bad gateway or failed dependency

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**503** — Service is temporarily unavailable

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**504** — Gateway or dependency timeout

Content-Type: `*/*`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"