# Versions

> Part of the Cowliss docs. Markdown for every page: append `index.md` to its URL. Site map: /llms.txt

<!-- GENERATED by apps/docs/scripts/generate-api-reference.ts. Do not edit. Regenerate with `pnpm -F cowliss-docs generate`. -->

A version is an immutable, content-addressed snapshot of one automation or one template. It is read-only and addressed through its key rather than on its own path. Automations and templates share a key space, so both `key` and `kind` are required, and `appId` picks one app's history of a template key: a key one app holds needs none, and a key two apps hold is refused without it, as on the template routes. The latest `ready` version is what new executions and new sends use; a Liquid or doc template's version is ready the moment it is written.

## GET /v1/versions

List an automation's or a template's versions, newest first

**Auth:** Session token.

**Query parameters**

```json
{
  "cursor": "string",
  "limit": 50,
  "key": "string",
  "kind": "automation",
  "appId": "string"
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `cursor` | string | no |  |
| `limit` | integer | no | default `50`; 1 ≤ x ≤ 100 |
| `key` | string | yes | length 1–200 |
| `kind` | "automation" \| "template" | yes |  |
| `appId` | string | no | length 0–200 |

**Response 200**

```json
{
  "data": [
    {
      "id": "string",
      "orgId": "string",
      "key": "string",
      "kind": "automation",
      "appId": "string",
      "source": "push",
      "moduleDigest": "string",
      "manifest": {
        "key": "string",
        "tags": {},
        "trigger": {
          "event": "string"
        },
        "purpose": "string",
        "enrollment": {
          "cooldown": "string"
        },
        "description": "string",
        "from": "string",
        "definition": {
          "trigger": {
            "event": "string"
          },
          "purpose": "marketing",
          "from": "string",
          "tags": {},
          "description": "string",
          "enrollment": {
            "cooldown": "string"
          },
          "steps": [
            {
              "id": "string",
              "type": "sleep",
              "duration": "string"
            }
          ]
        },
        "spine": [
          {
            "name": "sleep",
            "detail": "string",
            "timeout": "string",
            "steps": [],
            "otherwise": []
          }
        ],
        "bundle": "string"
      },
      "protocol": 42,
      "status": "compiling",
      "pushedAt": "2026-01-15T09:30:00.000Z",
      "compiledAt": "2026-01-15T09:30:00.000Z",
      "error": "string"
    }
  ],
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `data` | object[] | yes |  |
| `data[]` | object | yes |  |
| `data[].id` | string | yes |  |
| `data[].orgId` | string | yes |  |
| `data[].key` | string | yes |  |
| `data[].kind` | "automation" \| "template" | yes |  |
| `data[].appId` | string | yes |  |
| `data[].source` | "push" \| "api" | yes |  |
| `data[].moduleDigest` | string \| null | yes |  |
| `data[].manifest` | object \| object | yes |  |
| `data[].protocol` | integer | yes | -2147483648 ≤ x ≤ 2147483647 |
| `data[].status` | "compiling" \| "ready" \| "failed" | yes |  |
| `data[].pushedAt` | string (date-time) | yes |  |
| `data[].compiledAt` | string (date-time) \| null | yes |  |
| `data[].error` | string \| null | yes |  |
| `meta` | object | no |  |
| `meta.requestId` | string | no |  |
| `meta.nextCursor` | string \| null | no |  |
| `meta.hasMore` | boolean | no |  |
| `meta.warnings` | object[] | no |  |
| `meta.warnings[]` | object | no |  |
| `meta.warnings[].code` | string | yes |  |
| `meta.warnings[].message` | string | yes |  |
| `meta.warnings[].suggestion` | string | no |  |

Errors follow the [shared envelope and code table](/api-conventions/#errors).