# Registration (https://developer.godaddy.com/en/docs/references/rest/ans/registration)

***

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

* depth: 2
  title: Register a new agent with the ANS
  url: '#register-a-new-agent-with-the-ans'
* depth: 2
  title: Retrieve agent details
  url: '#retrieve-agent-details'
  structuredData:
  headings:
  * content: Register a new agent with the ANS
    id: register-a-new-agent-with-the-ans
  * content: Retrieve agent details
    id: retrieve-agent-details
    contents:
  * content: >
    Registers a new agent with the Agent Name Service. Supports three
    registration flows:

    1. GoDaddy domains with CSRs (synchronous) - Returns 202 immediately
       with wait instruction

    2. External domains with CSRs (async ACME) or BYOC - Returns 202 with
       validation requirements. BYOC is permitted for server certificates
       only; identity certificates are always issued by the RA.

    The Registration Authority (RA) validates the agent's identity and
    submitted

    information, then interacts with the CA to issue certificates or
    validates

    provided server certificates.
    heading: register-a-new-agent-with-the-ans
  * content: Retrieves detailed information about a registered agent
    heading: retrieve-agent-details

***

## POST /v1/agents/register

Register a new agent with the ANS

Registers a new agent with the Agent Name Service. Supports three registration flows:
1. GoDaddy domains with CSRs (synchronous) - Returns 202 immediately with wait instruction
2. External domains with CSRs (async ACME) or BYOC - Returns 202 with validation requirements. BYOC is permitted for server certificates only; identity certificates are always issued by the RA.

The Registration Authority (RA) validates the agent's identity and submitted
information, then interacts with the CA to issue certificates or validates
provided server certificates.


### Request body (required)

Agent registration request

Content-Type: `application/json`

Schema:

- object — Registration request
  - `agentDescription`: string — Description of the agent
  - `agentDisplayName` (required): string — Human-readable display name for the agent
  - `agentHost` (required): string — The fully qualified domain name (FQDN) where the agent is hosted
  - `endpoints` (required): array — Array of agent endpoints with protocol-specific configuration
      - items:
          - `agentUrl` (required): string <uri> — The URL where the agent is hosted and accepts requests
          - `metaDataUrl`: string <uri> — URL for agent metadata (optional)
          - `documentationUrl`: string <uri> — URL for agent documentation (optional)
          - `protocol` (required): string — Communication protocol for this endpoint
            - enum: "A2A", "MCP", "HTTP-API"
          - `functions`: array — Array of functions provided by this endpoint. The meaning varies by protocol: for MCP these are tools (e.g., 'domain_suggest', 'file_search'), for A2A these are skills (e.g., 'translate_document', 'analyze_sentiment'), and for HTTP-API these are routes (e.g., 'GET /domains', 'POST /orders'). (optional)
              - items:
                  - `id` (required): string — Unique identifier for the function
                  - `name` (required): string — Human-readable name for the function
                  - `tags`: array — Tags for categorizing and discovering functions (max 5 tags, each up to 20 characters)
                      - items:
          - `transports`: array — Supported transport mechanisms for the protocol (optional)
              - items:
                  - enum: "STREAMABLE-HTTP", "SSE", "JSON-RPC", "GRPC", "REST", "HTTP"
  - `identityCsrPEM` (required): string — Base64 encoded PEM certificate signing request (CSR).
  - `serverCertificateChainPEM`: string — Optional - Base64 encoded PEMs of cert-chain of a server certificate. When this field is present, serverCertificatePEM must be specified. Both fields are used when client chooses BYOC for server certificate.
  - `serverCertificatePEM`: string — Base64 encoded PEM server certificate. Required when BYOC is used for server certificate.
  - `serverCsrPEM`: string — Base64 encoded PEM certificate signing request (CSR). Required when not using BYOC
  - `version` (required): string — Semantic Versioning format (major.minor.patch)

### Responses

**202** — Registration accepted, validation required (external domains)

Content-Type: `application/json`

```json
{
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "ansName": "ans://v1.0.0.external-domain.com",
  "challenge": {
    "dnsRecord": {
      "name": "_acme-challenge.external-domain.com",
      "type": "TXT",
      "value": "xyz123abc456"
    },
    "keyAuthorization": "xyz123abc456.thumbprint",
    "token": "xyz123abc456",
    "type": "DNS_01"
  },
  "expiresAt": "2025-11-13 16:30:00+00:00",
  "links": [
    {
      "href": "https://api.godaddy.com/v1/agents/550e8400-e29b-41d4-a716-446655440000/challenge",
      "rel": "challenge"
    }
  ],
  "nextSteps": [
    {
      "action": "CONFIGURE_DNS",
      "description": "Configure DNS TXT record for ACME validation",
      "endpoint": "https://api.godaddy.com/v1/agents/550e8400-e29b-41d4-a716-446655440000/verify-acme"
    }
  ],
  "status": "PENDING_VALIDATION"
}
```

Schema:

- object — Response for pending registration (external domains)
  - `ansName` (required): string — The ANS Name being registered in format ans://{version}.{agentHost}
  - `challenges`: array — Challenge options for domain verification
      - items:
          - `dnsRecord`: object
              - `name`: string
              - `type`: string
              - `value`: string
          - `expiresAt`: string <date-time>
          - `httpPath`: string
          - `keyAuthorization`: string — Key authorization string
          - `token`: string — Challenge token
          - `type`: string
            - enum: "DNS_01", "HTTP_01"
  - `dnsRecords`: array — DNS records to be configured
      - items:
          - `name` (required): string — Full DNS record name
          - `priority`: integer — For HTTPS records
          - `purpose`: string — Purpose of this DNS record
            - enum: "DISCOVERY", "TRUST", "CERTIFICATE_BINDING", "BADGE"
          - `required`: boolean — Whether this record is required
          - `ttl`: integer
          - `type` (required): string
            - enum: "HTTPS", "TLSA", "TXT"
          - `value` (required): string — Record value to set
  - `expiresAt`: string <date-time> — When this registration attempt expires
  - `links`: array
      - items:
          - `href` (required): string <uri> — Link URL
          - `rel` (required): string — Link relation type
  - `nextSteps` (required): array — Required actions to continue registration
      - items:
          - `action`: string
            - enum: "CONFIGURE_DNS", "CONFIGURE_HTTP", "VERIFY_DNS", "VALIDATE_DOMAIN", "WAIT"
          - `description`: string
          - `endpoint`: string <uri>
  - `status` (required): string — Current registration status
    - enum: "PENDING_VALIDATION", "PENDING_CERTS", "PENDING_DNS"

**401** — Authentication failed

Content-Type: `application/json`

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** — Authorization failed

Content-Type: `application/json`

Schema:

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

**409** — Agent ID or ANSName already exists

Content-Type: `application/json`

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** — Invalid registration request

Content-Type: `application/json`

```json
{
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "agentDisplayName",
    "reason": "Field is required but was not provided"
  },
  "message": "Invalid registration request: agentDisplayName is required",
  "status": "ERROR"
}
```

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: `application/json`

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/agents/{agentId}

Retrieve agent details

Retrieves detailed information about a registered agent

### Path parameters

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

### Responses

**200** — Agent details retrieved successfully

Content-Type: `application/json`

Schema:

- object
  - `agentDescription`: string — Description of the agent
  - `agentHost` (required): string — The agent's hosting domain
  - `agentId` (required): string — Unique identifier of the agent
  - `agentDisplayName`: string — Human-readable display name for the agent
  - `agentStatus` (required): string — Status of an agent in its registration and operational lifecycle
    - enum: "PENDING_VALIDATION", "PENDING_DNS", "ACTIVE", "FAILED", "EXPIRED", "REVOKED"
  - `ansName` (required): string — Fully qualified ANS name in format ans://{version}.{agentHost}
  - `endpoints` (required): array — Array of agent endpoints with protocol-specific configuration
      - items:
          - `agentUrl` (required): string <uri> — The URL where the agent is hosted and accepts requests
          - `metaDataUrl`: string <uri> — URL for agent metadata (optional)
          - `documentationUrl`: string <uri> — URL for agent documentation (optional)
          - `protocol` (required): string — Communication protocol for this endpoint
            - enum: "A2A", "MCP", "HTTP-API"
          - `functions`: array — Array of functions provided by this endpoint. The meaning varies by protocol: for MCP these are tools (e.g., 'domain_suggest', 'file_search'), for A2A these are skills (e.g., 'translate_document', 'analyze_sentiment'), and for HTTP-API these are routes (e.g., 'GET /domains', 'POST /orders'). (optional)
              - items:
                  - `id` (required): string — Unique identifier for the function
                  - `name` (required): string — Human-readable name for the function
                  - `tags`: array — Tags for categorizing and discovering functions (max 5 tags, each up to 20 characters)
                      - items:
          - `transports`: array — Supported transport mechanisms for the protocol (optional)
              - items:
                  - enum: "STREAMABLE-HTTP", "SSE", "JSON-RPC", "GRPC", "REST", "HTTP"
  - `lastRenewalTimestamp`: string <date-time>
  - `links` (required): array — HATEOAS links for related operations
      - items:
          - `href` (required): string <uri> — Link URL
          - `rel` (required): string — Link relation type
  - `registrationTimestamp`: string <date-time>
  - `version` (required): string
  - `registrationPending`: object — Response for pending registration (external domains)
      - `ansName` (required): string — The ANS Name being registered in format ans://{version}.{agentHost}
      - `challenges`: array — Challenge options for domain verification
          - items:
              - `dnsRecord`: object
                  - `name`: string
                  - `type`: string
                  - `value`: string
              - `expiresAt`: string <date-time>
              - `httpPath`: string
              - `keyAuthorization`: string — Key authorization string
              - `token`: string — Challenge token
              - `type`: string
                - enum: "DNS_01", "HTTP_01"
      - `dnsRecords`: array — DNS records to be configured
          - items:
              - `name` (required): string — Full DNS record name
              - `priority`: integer — For HTTPS records
              - `purpose`: string — Purpose of this DNS record
                - enum: "DISCOVERY", "TRUST", "CERTIFICATE_BINDING", "BADGE"
              - `required`: boolean — Whether this record is required
              - `ttl`: integer
              - `type` (required): string
                - enum: "HTTPS", "TLSA", "TXT"
              - `value` (required): string — Record value to set
      - `expiresAt`: string <date-time> — When this registration attempt expires
      - `links`: array
          - items:
              - `href` (required): string <uri> — Link URL
              - `rel` (required): string — Link relation type
      - `nextSteps` (required): array — Required actions to continue registration
          - items:
              - `action`: string
                - enum: "CONFIGURE_DNS", "CONFIGURE_HTTP", "VERIFY_DNS", "VALIDATE_DOMAIN", "WAIT"
              - `description`: string
              - `endpoint`: string <uri>
      - `status` (required): string — Current registration status
        - enum: "PENDING_VALIDATION", "PENDING_CERTS", "PENDING_DNS"

**401** — Authentication failed

Content-Type: `application/json`

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** — Authorization failed

Content-Type: `application/json`

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** — Agent not found

Content-Type: `application/json`

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: `application/json`

Schema:

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