Skip to main content

​
Full update

PUT /domains/{domain_id}
Replaces all writable fields on the domain in a single operation. All required fields must be included in the request body.
The subdomains field is replaced in its entirety. Any subdomain name not included in the new list will be removed from the domain. Indicators that belong to a removed subdomain are not automatically updated — they will retain a dangling subdomain reference and will no longer correspond to a valid subdomain on the domain.

​
Path parameters

​
domain_id
string
required
ObjectId string of the domain. Returns 400 if not a valid ObjectId format.

​
Request body

​
name
string
required
Display name of the domain.
​
color
string
required
CSS color for the domain (e.g., "#3B82F6" or "blue").
​
image
string
default:"\"\""
URL to a banner or representative image for the domain.
​
icon
string
default:"\"\""
URL to an icon image for the domain.
​
subdomains
string[]
required
Complete list of subdomain names. This replaces the existing list.

​
Response

Returns the updated Domain object.
​
id
string
required
ObjectId string of the domain.
​
name
string
required
Updated display name.
​
color
string
required
Updated CSS color.
​
image
string
Updated image URL.
​
icon
string
Updated icon URL.
​
subdomains
string[]
required
Updated list of subdomain names.

​
Errors

StatusCondition
400domain_id is not a valid ObjectId format
404No domain with the given ID exists

​
Examples

curl --request PUT \
  --url 'http://localhost:8080/domains/64a1f2b3c4d5e6f7a8b9c0a1' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Tourism flows",
    "color": "#2563EB",
    "image": "https://cdn.example.com/domains/tourism-flows.jpg",
    "icon": "https://cdn.example.com/icons/tourism-flows.svg",
    "subdomains": ["Visitor volume", "Visitor spending"]
  }'

​
Sample response

200
{
  "id": "64a1f2b3c4d5e6f7a8b9c0a1",
  "name": "Tourism flows",
  "color": "#2563EB",
  "image": "https://cdn.example.com/domains/tourism-flows.jpg",
  "icon": "https://cdn.example.com/icons/tourism-flows.svg",
  "subdomains": ["Visitor volume", "Visitor spending"]
}

​
Partial update

PATCH /domains/{domain_id}
Updates only the fields provided in the request body. Omitted fields are left unchanged.

​
Path parameters

​
domain_id
string
required
ObjectId string of the domain. Returns 400 if not a valid ObjectId format.

​
Request body

All fields are optional. Only include fields you want to change.
​
name
string
New display name for the domain.
​
color
string
New CSS color for the domain.
​
image
string
New image URL for the domain.
​
icon
string
New icon URL for the domain.
​
subdomains
string[]
New complete list of subdomain names. When provided, this replaces the existing list — the same subdomain removal caveats apply as with PUT.

​
Response

Returns the updated Domain object with the same fields as the full update response.

​
Errors

StatusCondition
400domain_id is not a valid ObjectId format
404No domain with the given ID exists

​
Examples

curl --request PATCH \
  --url 'http://localhost:8080/domains/64a1f2b3c4d5e6f7a8b9c0a1' \
  --header 'Content-Type: application/json' \
  --data '{
    "color": "#7C3AED"
  }'

​
Sample response

200
{
  "id": "64a1f2b3c4d5e6f7a8b9c0a1",
  "name": "Tourism flows",
  "color": "#7C3AED",
  "image": "https://cdn.example.com/domains/tourism-flows.jpg",
  "icon": "https://cdn.example.com/icons/tourism-flows.svg",
  "subdomains": ["Visitor volume", "Visitor spending", "Visitor origin"]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us