# Register a new agent with the ANS (https://developer.godaddy.com/en/docs/references/rest/ans/register-agent)

---
title: Register a new agent with the ANS
description: Registers a new agent with the Agent Name Service.
full: true
---

Full description

Registers a new agent with the Agent Name Service. Supports GoDaddy domains (synchronous, CSR-based), external domains (async ACME), and bring-your-own-certificate (BYOC, server certificates only). Returns 202 with registration status and any validation requirements.

## POST /v1/agents/register

Register a new agent with the ANS

Registers a new agent with the Agent Name Service. Supports GoDaddy domains (synchronous, CSR-based), external domains (async ACME), and bring-your-own-certificate (BYOC, server certificates only). Returns 202 with registration status and any validation requirements.

### Request body (required)

Agent registration request

Content-Type: `application/json`

Schema:

- schema reference: `#/components/schemas/AgentRegistrationRequest`

### 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:

- schema reference: `#/components/schemas/RegistrationPending`

**401** — Authentication failed

Content-Type: `application/json`

Schema:

- schema reference: `#/components/schemas/ErrorResponse`

**403** — Authorization failed

Content-Type: `application/json`

Schema:

- schema reference: `#/components/schemas/ErrorResponse`

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

Content-Type: `application/json`

Schema:

- schema reference: `#/components/schemas/ErrorResponse`

**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:

- schema reference: `#/components/schemas/ErrorResponse`

**500** — Internal server error

Content-Type: `application/json`

Schema:

- schema reference: `#/components/schemas/ErrorResponse`