Portfolios API

Portfolios group domains for organisational purposes. Create, rename, and delete portfolios, and query the domain count for each.

GET/api/v1/portfoliosAuth required

List all portfolios in your account.

Query Parameters

Parameter	Type	Required	Description
name	string	No	Filter by portfolio name (partial match)
limit	number	No	Max results, default 50
offset	number	No	Pagination offset, default 0

Response

json

{
  "portfolios": [
    {
      "id": "uuid",
      "name": "Production",
      "description": "All production domains",
      "domain_count": 12,
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "total": 1
}

GET/api/v1/portfolios/:idAuth required

Get a single portfolio by UUID.

Response

json

{
  "id": "uuid",
  "name": "Production",
  "description": "All production domains",
  "domain_count": 12,
  "created_at": "2026-01-01T00:00:00Z"
}

POST/api/v1/portfoliosAuth required

Create a new portfolio.

Request Body

Parameter	Type	Required	Description
name	string	Yes	Portfolio name
description	string	No	Optional description

Response

json

{
  "id": "uuid",
  "name": "Production",
  "description": "All production domains",
  "domain_count": 0,
  "created_at": "2026-03-28T09:00:00Z"
}

Error Codes

Status	Description
409	A portfolio with this name already exists

PUT/api/v1/portfolios/:idAuth required

Update a portfolio's name or description.

Request Body

Parameter	Type	Required	Description
name	string	No	New portfolio name
description	string	No	Updated description

Response

json

{
  "id": "uuid",
  "name": "Renamed Portfolio",
  "description": "Updated description",
  "domain_count": 12,
  "updated_at": "2026-03-28T09:00:00Z"
}

DELETE/api/v1/portfolios/:idAuth required

Delete a portfolio. The portfolio must be empty before deletion.

Response

json

{
  "message": "Portfolio deleted",
  "deleted_portfolio": {
    "id": "uuid",
    "name": "Production"
  }
}

Error Codes

Status	Description
409	Portfolio still contains domains. Remove or reassign domains first.