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

# Model Objects

Model objects are the nodes in your architecture graph. They represent the actors, systems, services, and components that make up your software architecture.

---

## Object types

IcePanel uses the

C4 model

's levels of abstraction. Each object type maps to a C4 level:

| Type        | C4 Level | Description                                                                                                                                          |
| ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `root`      | —        | The root node of every [domain](/core-concepts/domains). There is exactly one per domain. All top-level systems and actors are children of the root. |
| `actor`     | Level 1  | A person or external role that interacts with your architecture (e.g. "Customer", "Admin")                                                           |
| `system`    | Level 1  | A top-level software system (e.g. "IcePanel")                                                                                                        |
| `group`     | Level 1  | A visual grouping (e.g. "Worker Pool", "Subnet")                                                                                                     |
| `app`       | Level 2  | A deployable unit (container) inside a system: a service, web app, mobile app, or queue                                                              |
| `store`     | Level 2  | A persistent data store inside a system: a database, blob store, or cache                                                                            |
| `component` | Level 3  | An internal building block inside an `app` or `store`                                                                                                |

---

## The parent–child hierarchy

Model objects form a tree. Every object except `root` has a `parentId` pointing to its parent:

```
root
├── actor: Customer
├── system: Payment Service
│   ├── app: API Gateway
│   │   ├── component: Auth Middleware
│   │   └── component: Rate Limiter
│   ├── app: Payment Processor
│   └── store: Transactions DB
└── system: Auth Platform (external)
```

---

## Creating objects

To create a new object, specify the `landscapeId` and either the `versionId` or `latest`:

### Request

POST [https://api.icepanel.io/v1/landscapes/\{landscapeId}/versions/\{versionId}/model/objects](https://api.icepanel.io/v1/landscapes/\{landscapeId}/versions/\{versionId}/model/objects)

```curl
curl -X POST https://api.icepanel.io/v1/landscapes/landscapeId/versions/versionId/model/objects \
     -H "X-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "string",
  "parentId": "string",
  "type": "actor"
}'
```

```typescript
import { IcePanelClient } from "@icepanel/sdk";

async function main() {
    const client = new IcePanelClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.model.objects.create({
        landscapeId: "landscapeId",
        versionId: "versionId",
        body: {
            name: "string",
            parentId: "string",
            type: "actor",
        },
    });
}
main();

```

```java
package com.example.usage;

import com.icepanel.IcePanelClient;
import com.icepanel.core.OptionalNullable;
import com.icepanel.model.types.ModelObjectCreateRequest;
import com.icepanel.types.ModelObjectRequired;
import com.icepanel.types.ModelObjectType;

public class Example {
    public static void main(String[] args) {
        IcePanelClient client = IcePanelClient
            .builder()
            .apiKey("YOUR_API_KEY_HERE")
            .build();

        client.model().objects().create(
            ModelObjectCreateRequest
                .builder()
                .landscapeId("landscapeId")
                .versionId("versionId")
                .body(
                    ModelObjectRequired
                        .builder()
                        .name("string")
                        .type(ModelObjectType.ACTOR)
                        .parentId(
                            OptionalNullable.of("string")
                        )
                        .build()
                )
                .build()
        );
    }
}
```

```python
import requests

url = "https://api.icepanel.io/v1/landscapes/landscapeId/versions/versionId/model/objects"

payload = {
    "name": "string",
    "parentId": "string",
    "type": "actor"
}
headers = {
    "X-API-Key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```go
package main

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

func main() {

	url := "https://api.icepanel.io/v1/landscapes/landscapeId/versions/versionId/model/objects"

	payload := strings.NewReader("{\n  \"name\": \"string\",\n  \"parentId\": \"string\",\n  \"type\": \"actor\"\n}")

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

	req.Header.Add("X-API-Key", "<apiKey>")
	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))

}
```

```csharp
using RestSharp;

var client = new RestClient("https://api.icepanel.io/v1/landscapes/landscapeId/versions/versionId/model/objects");
var request = new RestRequest(Method.POST);
request.AddHeader("X-API-Key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"string\",\n  \"parentId\": \"string\",\n  \"type\": \"actor\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

---

## Filtering objects

To find the root object (required as `parentId` when creating top-level objects), use the query parameter `?filter[type]=root`

### Request

GET [https://api.icepanel.io/v1/landscapes/\{landscapeId}/versions/\{versionId}/model/objects](https://api.icepanel.io/v1/landscapes/\{landscapeId}/versions/\{versionId}/model/objects)

```curl
curl https://api.icepanel.io/v1/landscapes/landscapeId/versions/versionId/model/objects \
     -H "X-API-Key: <apiKey>"
```

```typescript
import { IcePanelClient } from "@icepanel/sdk";

async function main() {
    const client = new IcePanelClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.model.objects.list({
        landscapeId: "landscapeId",
        versionId: "versionId",
    });
}
main();

```

```java
package com.example.usage;

import com.icepanel.IcePanelClient;
import com.icepanel.model.types.ModelObjectsListRequest;

public class Example {
    public static void main(String[] args) {
        IcePanelClient client = IcePanelClient
            .builder()
            .apiKey("YOUR_API_KEY_HERE")
            .build();

        client.model().objects().list(
            ModelObjectsListRequest
                .builder()
                .landscapeId("landscapeId")
                .versionId("versionId")
                .build()
        );
    }
}
```

```python
import requests

url = "https://api.icepanel.io/v1/landscapes/landscapeId/versions/versionId/model/objects"

headers = {"X-API-Key": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```go
package main

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

func main() {

	url := "https://api.icepanel.io/v1/landscapes/landscapeId/versions/versionId/model/objects"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<apiKey>")

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

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

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

}
```

```csharp
using RestSharp;

var client = new RestClient("https://api.icepanel.io/v1/landscapes/landscapeId/versions/versionId/model/objects");
var request = new RestRequest(Method.GET);
request.AddHeader("X-API-Key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

The `GET /model/objects` endpoint supports the following filters:

| Query parameter           | Description                                          |
| ------------------------- | ---------------------------------------------------- |
| `filter[type]`            | Object type                                          |
| `filter[status]`          | Status lifecycle value                               |
| `filter[parentId]`        | Direct parent ID                                     |
| `filter[domainId]`        | Domain ID                                            |
| `filter[external]`        | `true` / `false`                                     |
| `filter[tagIds][]`        | One or more tag IDs                                  |
| `filter[teamIds][]`       | One or more team IDs                                 |
| `filter[technologyIds][]` | One or more technology IDs                           |
| `filter[labels][key]`     | Label key-value pair                                 |
| `filter[name]`            | Partial name match                                   |
| `filter[linked]`          | `true` to return only objects with at least one link |

---

## Status lifecycle

Objects and connections share a four-state lifecycle representing their architectural status:

```
live  →  deprecated  →  removed →  future
```

| Status       | Description                            |
| ------------ | -------------------------------------- |
| `live`       | Current, active element                |
| `future`     | Planned but not yet built              |
| `deprecated` | Still in use but being phased out      |
| `removed`    | Retired, kept for historical reference |

Use the `filter[status]` query parameter to retrieve only objects with a given status.

---

## Related concepts

* [Model Connections](/core-concepts/model-connections)