REST API

Introduction

The IcePanel REST API is publicly accessible to write automated scripts or custom integrations with external tools.

Our OpenAPI 3.0 specification can be found at api.icepanel.io and opened by importing it into Postman.

Authentication

First generate an API key on your organization management screen. Make sure to copy your key now as you won't be able to see it again for security reasons!

You can then set the Authorization HTTP header on any authenticated requests.

Authorization: ApiKey SH5XAiWtgevC2ZfQym3i:17a9c60035eed62c8f4f195c754ee6972ffc40ce975c5571ec521f463ebefa7f

Example

See the example below for how to request a list of projects using curl.

curl 'https://api.icepanel.io/v1/organizations/{organizationId}/landscapes' \
  -H 'Accept: application/json' \                                                                                
  -H 'Authorization: ApiKey SH5XAiWtgevC2ZfQym3i:17a9c60035eed62c8f4f195c754ee6972ffc40ce975c5571ec521f463ebefa7f'

Use Cases

Export objects and relationships

The object and relationship data that IcePanel stores as part of the model has great uses. For example informing an incident response team about up and downstream dependencies of a service as well as which team owns the service.

Export objects and connections in CSV format which is great for importing to spreadsheets.

curl https://api.icepanel.io/v1/landscapes/{landscapeId}/versions/latest/model/objects/export/csv

curl https://api.icepanel.io/v1/landscapes/{landscapeId}/versions/latest/model/connections/export/csv

Export the whole model as JSON which can be easily used as part of a build pipeline, script or automation. This also includes flows which the CSV export does not.

curl https://api.icepanel.io/v1/landscapes/{landscapeId}/versions/latest/export/json

Update model descriptions with Markdown

Use the existing Markdown documentation stored in a code repository to populate the descriptions of your IcePanel model objects and connections. This can be automatically updated as part of a build pipeline.

First fetch a list of the model objects that exist in your landscape and find the identifier to update.

curl https://api.icepanel.io/v1/landscapes/{landscapeId}/versions/latest/model/objects

Then patch the model object identifier with your Markdown description.

curl -X PATCH https://api.icepanel.io/v1/landscapes/{landscapeId}/versions/latest/model/objects/{modelObjectId} \
  -H 'Authorization: ApiKey {apiKey}' \
  -d '{"description": "# Heading\nbody"}'

Create model objects

Create objects in your model, great for automatically filling out your model from another source.

First use a GET request to find the root model object, your landscape may have multiple root model objects if you use domains.

curl -g 'https://api.icepanel.io/v1/landscapes/{landscapeId}/versions/latest/model/objects?filter[type]=root' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ApiKey {apiKey}'

Once you've found the root model object pass the id to the parentId property of POST request to create a model objects inside it.

curl -X POST https://api.icepanel.io/v1/landscapes/{landscapeId}/versions/latest/model/objects \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ApiKey {apiKey}' \
  -d '{"name": "New system", "type": "system", "parentId": "{parentId}"}'

Create a version of your landscape

Version your landscape and create a snapshot in time on your version timeline. This can be run automatically as part of a build or release pipeline.

curl -X POST https://api.icepanel.io/v1/landscapes/{landscapeId}/versions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ApiKey {apiKey}' \
  -d '{"name": "1.0", "notes": "Version 1.0", "modelHandleId": null}'

Attach metadata to resources

The main resource types in IcePanel have a labels property for storing additional key/value metadata. The field is designed to make it easier to work with the API and is not used by the IcePanel app.

You can assign labels to resources using POST, PATCH or PUT requests.

curl -X PATCH https://api.icepanel.io/v1/landscapes/{landscapeId}/versions/latest/model/objects/{modelObjectId} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ApiKey {apiKey}' \
  -d '{"labels": {"cloudId": "x"}}'

You can then use GET requests to filter based on label values.

curl -g 'https://api.icepanel.io/v1/landscapes/{landscapeId}/versions/latest/model/objects?filter[labels][cloudId]=x' \
  -H 'Authorization: ApiKey {apiKey}'