> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scalacomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Curated example configurations

Curated example configurations

## Endpoints

| Method | Path | Description |
| - | - | - |
| GET | `/api/v1/templates` | List templates |
| POST | `/api/v1/templates` | Create template |
| GET | `/api/v1/templates/{template_id}` | Get template details |
| POST | `/api/v1/templates/{template_id}/clone` | Clone template to workspace |

***

## List templates

GET `/api/v1/templates`

### Parameters

| Name | In | Type | Required | Description |
| - | - | - | - | - |
| `limit` | query | integer | No | - |
| `next` | query | string | No | Opaque cursor token to fetch results after a specific item |
| `category` | query | string | No | Filter by template category |
| `search` | query | string | No | Full-text search across name and description fields (case-insensitive) |

### Responses

**200** - List of templates

```json theme={null}
{
  "templates": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "category": "..."
    }
  ],
  "pagination": {
    "count": 1,
    "hasMore": true,
    "nextCursor": "string"
  }
}
```

***

## Create template

POST `/api/v1/templates`

### Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Template name |
| `description` | string | Yes | Human-readable description |
| `category` | TemplateCategory | Yes | Category of template |
| `components` | array\[ComponentDeclaration] | No | Component declarations with typedParameters |
| `containers` | array\[ContainerDefinition] | No | Container definitions |
| `topology` | TopologyDefinition | No | Topology definition with links as ComponentDeclaration (type: layer) |
| `topology.name` | string (nullable) | No | Topology instance name (e.g., 'TestTopology') |
| `topology.type` | TopologyType | Yes, within `topology` | Network topology architecture type |
| `topology.topologyTiers` | integer | Yes, within `topology` | Number of tiers in CLOS topology (e.g., 3 for spine-fabric-rack) |
| `topology.allowedComponents` | array\[string] | Yes, within `topology` | Component types allowed at topology level (e.g., \['switch', 'layer', 'pod']) |
| `topology.components` | array\[ComponentReference] | Yes, within `topology` | Top-level component references (spine switches, pods). Containers are referenced by name with type='rack' or type='pod'. |
| `topology.appDistribution` | AppDistribution | No | Application distribution settings for random placement |
| `topology.appDistribution.description` | string (nullable) | No | Human-readable description of the distribution strategy |
| `topology.appDistribution.randomApplicationDistribution` | array\[RandomApplicationDistribution] | Yes, within `topology.appDistribution` | List of applications with their distribution percentages |
| `globalParameters` | TypedParameters | No | Global parameters in TypedParameters format |
| `applications` | array\[ApplicationDefinition] | No | Traffic generator and workload applications |
| `links` | array\[ComponentDeclaration] | No | Layer components defining spine plane linking configuration (type='layer') |

```json theme={null}
{
  "name": "string",
  "description": "string",
  "category": "getting-started",
  "components": [
    {
      "type": "...",
      "trafficType": "...",
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "version": "3.2.1",
      "typedParameters": "...",
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ]
    }
  ],
  "containers": [
    {
      "type": "...",
      "name": "roce-rack",
      "model": "ScalaRack",
      "version": "4.0.0",
      "configuration": null,
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ]
    }
  ],
  "topology": {
    "name": null,
    "type": "clos",
    "topologyTiers": 1,
    "allowedComponents": [
      "string"
    ],
    "components": [
      "..."
    ],
    "appDistribution": {
      "description": "...",
      "randomApplicationDistribution": "..."
    }
  },
  "globalParameters": {},
  "applications": [
    {
      "type": "...",
      "trafficType": "...",
      "name": "ScalaChakraGenerator",
      "model": "ChakraWorkload",
      "version": "4.0.1",
      "typedParameters": "..."
    }
  ],
  "links": [
    {
      "type": "...",
      "trafficType": "...",
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "version": "3.2.1",
      "typedParameters": "...",
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ]
    }
  ]
}
```

### Responses

**201** - Template created

```json theme={null}
{
  "id": "string",
  "name": "string",
  "description": "string",
  "category": "getting-started",
  "configuration": {
    "id": "config_10045",
    "workspaceId": "string",
    "name": "string",
    "status": "draft",
    "createdAt": "2024-01-15T10:30:00Z",
    "modifiedAt": "2024-01-15T10:30:00Z",
    "version": 1,
    "componentCount": 1,
    "components": [
      "..."
    ],
    "containers": [
      "..."
    ],
    "applications": [
      "..."
    ],
    "links": [
      "..."
    ],
    "topology": {
      "name": "...",
      "type": "...",
      "topologyTiers": "...",
      "allowedComponents": "...",
      "components": "...",
      "appDistribution": "..."
    },
    "globalParameters": {},
    "activeTraceset": {
      "name": "...",
      "id": "..."
    }
  }
}
```

***

## Get template details

GET `/api/v1/templates/{template_id}`

### Parameters

| Name | In | Type | Required | Description |
| - | - | - | - | - |
| `template_id` | path | string | Yes | - |

### Responses

**200** - Template details

```json theme={null}
{
  "id": "string",
  "name": "string",
  "description": "string",
  "category": "getting-started",
  "configuration": {
    "id": "config_10045",
    "workspaceId": "string",
    "name": "string",
    "status": "draft",
    "createdAt": "2024-01-15T10:30:00Z",
    "modifiedAt": "2024-01-15T10:30:00Z",
    "version": 1,
    "componentCount": 1,
    "components": [
      "..."
    ],
    "containers": [
      "..."
    ],
    "applications": [
      "..."
    ],
    "links": [
      "..."
    ],
    "topology": {
      "name": "...",
      "type": "...",
      "topologyTiers": "...",
      "allowedComponents": "...",
      "components": "...",
      "appDistribution": "..."
    },
    "globalParameters": {},
    "activeTraceset": {
      "name": "...",
      "id": "..."
    }
  }
}
```

***

## Clone template to workspace

POST `/api/v1/templates/{template_id}/clone`

### Parameters

| Name | In | Type | Required | Description |
| - | - | - | - | - |
| `template_id` | path | string | Yes | - |

### Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `workspaceId` | string | No | Target workspace identifier |
| `name` | string | Yes | Name for the new configuration |

```json theme={null}
{
  "workspaceId": "string",
  "name": "string"
}
```

### Responses

**201** - Configuration created

```json theme={null}
{
  "id": "config_10045",
  "workspaceId": "string",
  "name": "string",
  "status": "draft",
  "createdAt": "2024-01-15T10:30:00Z",
  "modifiedAt": "2024-01-15T10:30:00Z",
  "version": 1,
  "componentCount": 1,
  "components": [
    {
      "type": "...",
      "trafficType": "...",
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "version": "3.2.1",
      "typedParameters": "...",
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ]
    }
  ],
  "containers": [
    {
      "type": "...",
      "name": "roce-rack",
      "model": "ScalaRack",
      "version": "4.0.0",
      "configuration": null,
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ]
    }
  ],
  "applications": [
    {
      "type": "...",
      "trafficType": "...",
      "name": "ScalaChakraGenerator",
      "model": "ChakraWorkload",
      "version": "4.0.1",
      "typedParameters": "..."
    }
  ],
  "links": [
    {
      "type": "...",
      "trafficType": "...",
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "version": "3.2.1",
      "typedParameters": "...",
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ]
    }
  ],
  "topology": {
    "name": null,
    "type": "clos",
    "topologyTiers": 1,
    "allowedComponents": [
      "string"
    ],
    "components": [
      "..."
    ],
    "appDistribution": {
      "description": "...",
      "randomApplicationDistribution": "..."
    }
  },
  "globalParameters": {},
  "activeTraceset": {
    "name": "string",
    "id": "string"
  }
}
```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.