# Templates

> One-click project templates.

One-click project templates.

| Operation | Method and path |
| --- | --- |
| [List templates](#list-templates) | `GET /v1/templates` |
| [Get a template](#get-a-template) | `GET /v1/templates/{template}` |
| [Create a project from a template and deploy it](#create-a-project-from-a-template-and-deploy-it) | `POST /v1/templates/{template}/deploy` |

## List templates

```http
GET /v1/templates
```

- **Operation:** `listTemplates`
- **Scopes:** none (public)
- **Paginated:** `?limit=` and `?cursor=`

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `tag` | query | string |  |
| `q` | query | string |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| `200` OK | A page of Template objects. | [TemplateList](/docs/api/objects/template-list/) |

**Errors:** `400`, `429`, `500`, as [problem+json](/errors/) with a stable `code`.

**Example**

```bash
curl https://api.guv.dev/v1/templates \
  -H "Authorization: Bearer $GUV_TOKEN"
```

**Example response**

```json
{
  "data": [
    {
      "slug": "nextjs-postgres",
      "name": "Next.js + Postgres",
      "summary": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "icon_url": "https://guv.dev/",
      "repo": {
        "url": "https://guv.dev/",
        "path": "string"
      },
      "services": [
        {
          "name": "string",
          "kind": "string"
        }
      ],
      "databases": [
        "postgres"
      ],
      "estimated_monthly_cost": {
        "amount": "7.42",
        "currency": "GBP",
        "display": "£7.42"
      },
      "variables": [
        {
          "name": "string",
          "description": "string",
          "secret": false,
          "required": false,
          "generate": false
        }
      ],
      "manifest": "string",
      "verified_at": "2026-10-22T13:05:00Z"
    }
  ],
  "next_cursor": "string",
  "has_more": false
}
```

## Get a template

```http
GET /v1/templates/{template}
```

- **Operation:** `getTemplate`
- **Scopes:** none (public)

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `template` * | path | string | Template slug. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| `200` OK | OK. | [Template](/docs/api/objects/template/) |

**Errors:** `400`, `404`, `429`, `500`, as [problem+json](/errors/) with a stable `code`.

**Example**

```bash
curl https://api.guv.dev/v1/templates/template \
  -H "Authorization: Bearer $GUV_TOKEN"
```

**Example response**

```json
{
  "slug": "nextjs-postgres",
  "name": "Next.js + Postgres",
  "summary": "string",
  "description": "string",
  "tags": [
    "string"
  ],
  "icon_url": "https://guv.dev/",
  "repo": {
    "url": "https://guv.dev/",
    "path": "string"
  },
  "services": [
    {
      "name": "string",
      "kind": "string"
    }
  ],
  "databases": [
    "postgres"
  ],
  "estimated_monthly_cost": {
    "amount": "7.42",
    "currency": "GBP",
    "display": "£7.42"
  },
  "variables": [
    {
      "name": "string",
      "description": "string",
      "secret": false,
      "required": false,
      "generate": false
    }
  ],
  "manifest": "string",
  "verified_at": "2026-10-22T13:05:00Z"
}
```

## Create a project from a template and deploy it

```http
POST /v1/templates/{template}/deploy
```

- **Operation:** `deployTemplate`
- **Scopes:** `projects:write`
- **Idempotency-Key:** required; supports `?dry_run=true`

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `template` * | path | string | Template slug. |

**Request body** (`application/json`, required): [TemplateDeployRequest](/docs/api/objects/template-deploy-request/)

| Field | Type | Description |
| --- | --- | --- |
| `workspace` * | string |  |
| `project_name` * | string |  |
| `region` | [Region](/docs/api/objects/region/) |  |
| `variables` | map of string to string | Values for the template's variables. Secret values are write-only. Write-only: never returned. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| `200` OK | Dry run. Nothing was changed; this is what would happen. | [Plan](/docs/api/objects/plan/) |
| `202` Accepted | Accepted. The work continues in the background; follow the operation. | [Operation](/docs/api/objects/operation/) |

**Errors:** `400`, `401`, `402`, `403`, `404`, `409`, `422`, `429`, `500`, as [problem+json](/errors/) with a stable `code`.

**Example**

```bash
curl -X POST https://api.guv.dev/v1/templates/template/deploy \
  -H "Authorization: Bearer $GUV_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace": "string",
  "project_name": "string",
  "region": "lon1",
  "variables": {
    "key": "string"
  }
}'
```

**Example response**

```json
{
  "id": "op_01jbx2m9k7q4r8t5v6w3y0z1op",
  "kind": "deployment.create",
  "status": "running",
  "summary": "Deploying web to production",
  "workspace_id": "ws_01jbx2m9k7q4r8t5v6w3y0z1ws",
  "project_id": "prj_01jbx2m9k7q4r8t5v6w3y0z1pr",
  "environment_id": "env_01jbx2m9k7q4r8t5v6w3y0z1en",
  "resource": {
    "type": "deployment",
    "id": "dep_01jbx2m9k7q4r8t5v6w3y0z1dp",
    "url": "/v1/deployments/dep_01jbx2m9k7q4r8t5v6w3y0z1dp"
  },
  "progress": {
    "current_step": "build",
    "completed_steps": 1,
    "total_steps": 6,
    "percent": 20
  },
  "steps": [
    {
      "name": "resolve",
      "title": "Reading your settings",
      "status": "succeeded",
      "attempt": 1,
      "started_at": "2026-10-23T14:02:00Z",
      "finished_at": "2026-10-23T14:02:01Z"
    },
    {
      "name": "build",
      "title": "Building your app",
      "status": "running",
      "attempt": 1,
      "started_at": "2026-10-23T14:02:01Z",
      "finished_at": null
    }
  ],
  "created_by": {
    "type": "user",
    "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
    "display": "Stewart Webb"
  },
  "created_at": "2026-10-23T14:02:00Z",
  "links": {
    "self": "/v1/operations/op_01jbx2m9k7q4r8t5v6w3y0z1op",
    "events": "/v1/operations/op_01jbx2m9k7q4r8t5v6w3y0z1op/events",
    "resource": "/v1/deployments/dep_01jbx2m9k7q4r8t5v6w3y0z1dp"
  }
}
```