Domains
A domain is a subject grouping over agents — for example Communication or Personal Growth. Domains carry a model portfolio (the models agents in the domain may use) and are the unit that workspaces map to.
Domains are either system domains, shared across the deployment, or domains you create, which are private to you. Listing returns your own domains and, by default, the system ones. You can create, rename, and delete your own domains; system domains are managed for you.
Separately, you can override which domain a tool belongs to for your own account. These tool overrides are per-user and never affect anyone else.
- GET /api/domains List domains
- POST /api/domains Create a domain
- GET /api/domains/{domain_id} Retrieve a domain
- PUT /api/domains/{domain_id} Update a domain
- DEL /api/domains/{domain_id} Delete a domain
- PUT /api/domains/{domain_id}/models Set domain models
- PUT /api/domains/{domain_id}/tools/{tool_name} Assign a tool to a domain
- DEL /api/domains/tools/{tool_name}/override Clear a tool's domain override
Paths are relative to /agent-hub-api
The domain object
A domain and its grouping metadata.
Attributes
-
idstringUnique identifier, a UUID.
-
namestringDisplay name.
-
slugstringURL-safe identifier.
-
descriptionnullable stringFree-text summary.
-
owner_user_idnullable integerThe owning user, or
nullfor a system domain. -
is_systembooleanWhether this is a system domain.
-
regulatedbooleanWhether agents in the domain are treated as operating in a regulated context.
-
context_instructionsnullable stringOptional guidance applied to agents in the domain.
-
created_atstringCreation timestamp, ISO 8601.
-
updated_atstringLast-update timestamp, ISO 8601.
{
"id": "b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90",
"name": "Communication",
"slug": "communication",
"description": "Agents for PR and communication tasks.",
"owner_user_id": null,
"is_system": true,
"regulated": false,
"context_instructions": null,
"created_at": "2026-09-01T09:30:00",
"updated_at": "2026-09-01T09:30:00"
}List domains
GET /agent-hub-api/api/domains
Returns the domains visible to the caller.
Returns the domains you own together with the system domains. Set include_system to false to return only your own domains.
- Authentication
- Bearer token How it works
Query parameters
-
include_systembooleanWhether to include system domains alongside your own.
Returns
Returns a list of domain objects under data.
curl "$VDF_BASE_URL/agent-hub-api/api/domains" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN"const response = await fetch(`${process.env.VDF_BASE_URL}/agent-hub-api/api/domains`, {
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
},
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.get(
f"{os.environ['VDF_BASE_URL']}/agent-hub-api/api/domains",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"data": [
{
"id": "b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90",
"name": "Communication",
"slug": "communication",
"description": "Agents for PR and communication tasks.",
"owner_user_id": null,
"is_system": true,
"regulated": false,
"created_at": "2026-09-01T09:30:00",
"updated_at": "2026-09-01T09:30:00"
}
]
}Create a domain
POST /agent-hub-api/api/domains
Creates a domain that you own.
Creates a domain owned by the caller. name is required; a slug is derived from it when omitted. The slug must be unique among your own domains.
- Authentication
- Bearer token How it works
Body parameters application/json
-
namestring RequiredDisplay name.
-
slugstringURL-safe identifier. Derived from
namewhen omitted. -
descriptionstringFree-text summary.
Returns
Returns the created domain object under data.
Errors
- 400
nameis missing, or a domain with this slug already exists in your scope. - 401 The request carries no usable user identity.
curl -X POST "$VDF_BASE_URL/agent-hub-api/api/domains" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Investor Relations",
"description": "Agents for investor communications."
}'const response = await fetch(`${process.env.VDF_BASE_URL}/agent-hub-api/api/domains`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Investor Relations',
description: 'Agents for investor communications.',
}),
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.post(
f"{os.environ['VDF_BASE_URL']}/agent-hub-api/api/domains",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
json={
"name": "Investor Relations",
"description": "Agents for investor communications.",
},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"data": {
"id": "c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f",
"name": "Investor Relations",
"slug": "investor-relations",
"description": "Agents for investor communications.",
"owner_user_id": 42,
"is_system": false,
"regulated": false,
"created_at": "2026-09-02T11:15:00",
"updated_at": "2026-09-02T11:15:00"
}
}Retrieve a domain
GET /agent-hub-api/api/domains/{domain_id}
Returns a single domain by its identifier.
- Authentication
- Bearer token How it works
Path parameters
-
domain_idstring RequiredThe domain identifier (UUID).
Returns
Returns the domain object under data.
Errors
- 401 The request carries no usable user identity.
- 404 No domain with this identifier exists.
curl "$VDF_BASE_URL/agent-hub-api/api/domains/b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN"const response = await fetch(`${process.env.VDF_BASE_URL}/agent-hub-api/api/domains/b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90`, {
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
},
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.get(
f"{os.environ['VDF_BASE_URL']}/agent-hub-api/api/domains/b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"data": {
"id": "b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90",
"name": "Communication",
"slug": "communication",
"description": "Agents for PR and communication tasks.",
"owner_user_id": null,
"is_system": true,
"regulated": false,
"created_at": "2026-09-01T09:30:00",
"updated_at": "2026-09-01T09:30:00"
}
}Update a domain
PUT /agent-hub-api/api/domains/{domain_id}
Renames or re-describes a domain you own. Changing the name or slug re-derives the slug, which must stay unique in your scope. Only the owner may update a domain; anything else returns 404.
- Authentication
- Bearer token How it works
Path parameters
-
domain_idstring RequiredThe domain identifier (UUID).
Body parameters application/json
-
namestringNew display name.
-
slugstringNew URL-safe identifier.
-
descriptionstringNew free-text summary.
Returns
Returns the updated domain object under data.
Errors
- 401 The request carries no usable user identity.
- 404 No domain with this identifier is owned by the caller, or the update is not allowed.
curl -X PUT "$VDF_BASE_URL/agent-hub-api/api/domains/c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"description": "Agents for investor and analyst communications."
}'const response = await fetch(`${process.env.VDF_BASE_URL}/agent-hub-api/api/domains/c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
description: 'Agents for investor and analyst communications.',
}),
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.put(
f"{os.environ['VDF_BASE_URL']}/agent-hub-api/api/domains/c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
json={
"description": "Agents for investor and analyst communications.",
},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"data": {
"id": "c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f",
"name": "Investor Relations",
"slug": "investor-relations",
"description": "Agents for investor and analyst communications.",
"owner_user_id": 42,
"is_system": false,
"regulated": false,
"updated_at": "2026-09-02T12:00:00"
}
}Delete a domain
DEL /agent-hub-api/api/domains/{domain_id}
Deletes an empty domain you own.
Deletes a domain you own, provided no agents still belong to it. Only the owner may delete a domain, and a domain that still has agents cannot be deleted.
- Authentication
- Bearer token How it works
Path parameters
-
domain_idstring RequiredThe domain identifier (UUID).
Returns
Returns success: true and a confirmation message once the domain is deleted.
Errors
- 400 The domain is not owned by the caller, still has agents, or cannot be deleted.
- 401 The request carries no usable user identity.
curl -X DELETE "$VDF_BASE_URL/agent-hub-api/api/domains/c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN"const response = await fetch(`${process.env.VDF_BASE_URL}/agent-hub-api/api/domains/c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f`, {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
},
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.delete(
f"{os.environ['VDF_BASE_URL']}/agent-hub-api/api/domains/c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"message": "Domain deleted"
}Set domain models
PUT /agent-hub-api/api/domains/{domain_id}/models
Replaces a domain's model portfolio.
Replaces the set of models associated with a domain you own. Every name is validated against your model catalogue; an unknown model fails the whole request. Passing an empty list clears the portfolio.
- Authentication
- Bearer token How it works
Path parameters
-
domain_idstring RequiredThe domain identifier (UUID).
Body parameters application/json
-
model_namesarray of stringsThe model identifiers to associate with the domain. An empty list clears the portfolio.
Returns
Returns the resulting domain-model associations under data.
Errors
- 400
model_namesis not a list, or a model is not in your catalogue. - 401 The request carries no usable user identity.
curl -X PUT "$VDF_BASE_URL/agent-hub-api/api/domains/c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f/models" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model_names": [
"llama-3.3-70b-instruct"
]
}'const response = await fetch(`${process.env.VDF_BASE_URL}/agent-hub-api/api/domains/c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f/models`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model_names: ['llama-3.3-70b-instruct'],
}),
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.put(
f"{os.environ['VDF_BASE_URL']}/agent-hub-api/api/domains/c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f/models",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
json={
"model_names": ["llama-3.3-70b-instruct"],
},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"data": [
{
"id": "d0e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f",
"domain_id": "c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f",
"model_name": "llama-3.3-70b-instruct"
}
]
}Assign a tool to a domain
PUT /agent-hub-api/api/domains/{domain_id}/tools/{tool_name}
Overrides, for the caller, which domain a tool belongs to.
Sets a per-user override so that, for you, the named tool is filed under the given domain. The override applies only to your account. The target domain must be one you can use — a system domain or one you own.
- Authentication
- Bearer token How it works
Path parameters
-
domain_idstring RequiredThe domain identifier (UUID) to file the tool under.
-
tool_namestring RequiredThe tool to override.
Returns
Returns the resulting override under data.
Errors
- 400 The tool or domain does not exist, or the domain is not usable by the caller.
- 401 The request carries no usable user identity.
curl -X PUT "$VDF_BASE_URL/agent-hub-api/api/domains/c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f/tools/web_search" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN"const response = await fetch(`${process.env.VDF_BASE_URL}/agent-hub-api/api/domains/c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f/tools/web_search`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
},
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.put(
f"{os.environ['VDF_BASE_URL']}/agent-hub-api/api/domains/c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f/tools/web_search",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"data": {
"id": "e1f2a3b4-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
"owner_user_id": 42,
"tool_name": "web_search",
"domain_id": "c9e1f2a3-4b5c-4d6e-8f90-1a2b3c4d5e6f",
"domain_slug": "investor-relations"
}
}Clear a tool's domain override
DEL /agent-hub-api/api/domains/tools/{tool_name}/override
Removes the caller's domain override for a tool.
Removes your per-user domain override for the named tool, so it reverts to its default domain for you.
- Authentication
- Bearer token How it works
Path parameters
-
tool_namestring RequiredThe tool whose override should be removed.
Returns
Returns success: true and a confirmation message once the override is cleared.
Errors
- 401 The request carries no usable user identity.
- 404 No override exists for this tool.
curl -X DELETE "$VDF_BASE_URL/agent-hub-api/api/domains/tools/web_search/override" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN"const response = await fetch(`${process.env.VDF_BASE_URL}/agent-hub-api/api/domains/tools/web_search/override`, {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
},
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.delete(
f"{os.environ['VDF_BASE_URL']}/agent-hub-api/api/domains/tools/web_search/override",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"message": "Tool domain override cleared"
}