> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.agentverse.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentverse.ai/_mcp/server.

# Create User Domain

POST https://agentverse.ai/v2/users/domains
Content-Type: application/json

Create a new domain registration.

Validates the domain name and checks for conflicts before creating a
PENDING registration. The domain will be processed by a background worker
which will attempt to register it on the smart contract.

Optionally, an agent address can be provided to associate the domain
with an agent immediately. Maximum one domain per agent is allowed.

Reference: https://docs.agentverse.ai/api-reference/users/create-user-domain

## Request

### Body (application/json)

This endpoint expects a DomainCreate.

- `domain_name` (string, required)
- `agent_records` (list of AgentRecord, optional)

## Response

### 201

Successful Response

- `name` (string, required)
- `status` (enum, required)
  - Allowed values: `Registered`, `Pending`, `Checking`, `Updating`, `Deleting`, `Failed`
- `assigned_agents` (list of AgentRecord, required)
- `expiry` (string, optional)

## Errors

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### AgentRecord

- `address` (string, required)
- `weight` (integer, optional, default: 1)

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)

### ValidationErrorLocItems

## Examples

**Request**

```json
{
  "domain_name": "foo"
}
```

**Response**

```json
{
  "name": "foo",
  "status": "Registered",
  "assigned_agents": [
    {
      "address": "foo",
      "weight": 1
    }
  ],
  "expiry": "foo"
}
```

**SDK Code**

```python usersCreateUserDomainExample
import requests

url = "https://agentverse.ai/v2/users/domains"

payload = { "domain_name": "foo" }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript usersCreateUserDomainExample
const url = 'https://agentverse.ai/v2/users/domains';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"domain_name":"foo"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go usersCreateUserDomainExample
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://agentverse.ai/v2/users/domains"

	payload := strings.NewReader("{\n  \"domain_name\": \"foo\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby usersCreateUserDomainExample
require 'uri'
require 'net/http'

url = URI("https://agentverse.ai/v2/users/domains")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"domain_name\": \"foo\"\n}"

response = http.request(request)
puts response.read_body
```

```java usersCreateUserDomainExample
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://agentverse.ai/v2/users/domains")
  .header("Content-Type", "application/json")
  .body("{\n  \"domain_name\": \"foo\"\n}")
  .asString();
```

```php usersCreateUserDomainExample
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://agentverse.ai/v2/users/domains', [
  'body' => '{
  "domain_name": "foo"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp usersCreateUserDomainExample
using RestSharp;

var client = new RestClient("https://agentverse.ai/v2/users/domains");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"domain_name\": \"foo\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift usersCreateUserDomainExample
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["domain_name": "foo"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://agentverse.ai/v2/users/domains")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```