Skip to main content

​
Create domain

POST /domains/
Creates a new domain and returns the full Domain object.

​
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
Ordered list of subdomain names to create within this domain. Pass an empty array if no subdomains are needed yet.

​
Response

Returns the created Domain object.
​
id
string
required
ObjectId string of the newly created domain.
​
name
string
required
Display name of the domain.
​
color
string
required
CSS color associated with the domain.
​
image
string
Image URL. Empty string if not provided.
​
icon
string
Icon URL. Empty string if not provided.
​
subdomains
string[]
required
List of subdomain names for this domain.

​
Examples

curl --request POST \
  --url 'http://localhost:8080/domains/' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Tourism flows",
    "color": "#3B82F6",
    "image": "",
    "icon": "",
    "subdomains": ["Visitor volume", "Visitor spending", "Visitor origin"]
  }'

​
Sample response

200
{
  "id": "64a1f2b3c4d5e6f7a8b9c0a1",
  "name": "Tourism flows",
  "color": "#3B82F6",
  "image": "",
  "icon": "",
  "subdomains": ["Visitor volume", "Visitor spending", "Visitor origin"]
}

​
Upload domain icon

POST /domains/{domain_id}/icon
Uploads an icon image for a domain. The file is proxied to the knowledge-base service, which stores it and returns a URL. The domain’s icon field is then updated automatically.
This endpoint requires the knowledge-base service to be running at http://knowledge-base:8080. If the service is unavailable, the upload will fail and the domain’s icon will not be updated.

​
Path parameters

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

​
Request body

Send the file as multipart/form-data.
​
file
file
required
The icon image file to upload.

​
Response

​
icon
object
required
Response from the knowledge-base service.
​
domain
object
required
The updated Domain object with the new icon URL applied.

​
Errors

StatusCondition
400domain_id is not a valid ObjectId format
404Domain with the given ID does not exist

​
Example

curl --request POST \
  --url 'http://localhost:8080/domains/64a1f2b3c4d5e6f7a8b9c0a1/icon' \
  --form 'file=@/path/to/icon.svg'

​
Sample response

200
{
  "icon": {
    "url": "https://cdn.example.com/icons/64a1f2b3c4d5e6f7a8b9c0a1-icon.svg"
  },
  "domain": {
    "id": "64a1f2b3c4d5e6f7a8b9c0a1",
    "name": "Tourism flows",
    "color": "#3B82F6",
    "image": "",
    "icon": "https://cdn.example.com/icons/64a1f2b3c4d5e6f7a8b9c0a1-icon.svg",
    "subdomains": ["Visitor volume", "Visitor spending", "Visitor origin"]
  }
}

​
Upload domain image

POST /domains/{domain_id}/image
Uploads a banner or representative image for a domain. The file is proxied to the knowledge-base service, which stores it and returns a URL. The domain’s image field is then updated automatically.
This endpoint requires the knowledge-base service to be running at http://knowledge-base:8080. If the service is unavailable, the upload will fail and the domain’s image will not be updated.

​
Path parameters

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

​
Request body

Send the file as multipart/form-data.
​
file
file
required
The image file to upload.

​
Response

​
image
object
required
Response from the knowledge-base service.
​
domain
object
required
The updated Domain object with the new image URL applied.

​
Errors

StatusCondition
400domain_id is not a valid ObjectId format
404Domain with the given ID does not exist

​
Example

curl --request POST \
  --url 'http://localhost:8080/domains/64a1f2b3c4d5e6f7a8b9c0a1/image' \
  --form 'file=@/path/to/banner.jpg'

​
Sample response

200
{
  "image": {
    "url": "https://cdn.example.com/domains/64a1f2b3c4d5e6f7a8b9c0a1-banner.jpg"
  },
  "domain": {
    "id": "64a1f2b3c4d5e6f7a8b9c0a1",
    "name": "Tourism flows",
    "color": "#3B82F6",
    "image": "https://cdn.example.com/domains/64a1f2b3c4d5e6f7a8b9c0a1-banner.jpg",
    "icon": "",
    "subdomains": ["Visitor volume", "Visitor spending", "Visitor origin"]
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us