---
title: "List an SMS template's versions"
method: GET
path: "/v1/sms/templates/{template_ref}/versions"
tags: ["sms-templates"]
---

# List an SMS template's versions

`GET /v1/sms/templates/{template_ref}/versions`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/sms/templates/{template_ref}/versions`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Returns a cursor-paginated version history, newest first. Each entry is shallow and names its variables and languages. Read a version item or one of its languages to retrieve text. A built-in template exposes its current catalogue content as one synthetic published version.

## Query parameters

- `sort` 'created_at': Field to sort SMS templates and their versions by.
- `order` 'asc' | 'desc': Sort direction, ascending or descending.
- `limit` integer
- `starting_after` string
- `ending_before` string

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

Paginated list of template versions.

- SMSTemplateVersionList
  - `data` SMSTemplateVersionSummary[], required: One page of the template's versions, newest first.
    - `id` string, required
    - `template_id` string, required
    - `version_number` integer, nullable, required: Sequential publication number. Null for the draft; a built-in template reports 1.
    - `status` 'draft' | 'published', required: Whether the version is the editable draft or published. Published workspace versions are immutable and remain `published` after a later version goes live. A built-in template's synthetic published version projects the current catalogue entry.
    - `revision` integer, required: The version's revision counter.
    - `variables` TemplateVariable[], required: Variables inferred from the version's text and shared by each language.
      - `key` string, required: The key this slot is filled by. When `system` is true it is the reserved `bird` key or a dotted path beneath it, such as `bird.contact.first_name`, and naming it in a send is rejected. Otherwise, on email and SMS it is the key you set in the send's `parameters` object, and on WhatsApp the `name` you repeat on the matching parameter inside `components`, or, for a template whose placeholders are positional, the position itself as `1`, `2` and so on.
      - `type` string, required: The value type this slot accepts. Built-in SMS templates use typed slots (`code`, `amount` and the rest), each of which rejects a value that does not match its `constraint`. Email, WhatsApp and workspace SMS templates use `text`. Workspace SMS parameters must be scalar values. Open enum: treat an unrecognized value as a future type rather than an error.
      - `required` boolean, required: Whether the send must supply this variable. Omitting a required value returns `422` on email, SMS, and WhatsApp sends. Always false when `system` is true, because you do not supply that slot's value.
      - `constraint` string, required: A plain-language description of what values this variable accepts. When `system` is true it names where Bird takes the value from instead, because there is no value for you to send.
      - `sensitive` boolean: Whether this slot's value is redacted from stored message content. A placeholder replaces the sensitive value in message history; transport queues can still carry the text needed for delivery.
      - `system` boolean: Whether the value comes from Bird rather than from the send. Absent means false. Only email templates have system slots, identified by the reserved `bird` key or a dotted path beneath it; every SMS and WhatsApp slot is yours to fill. A draft can also name a reserved key no Bird value fills, including `bird` itself: `constraint` says so, and publishing that draft is rejected.
    - `default_language` string, required: A language tag in BCP-47 form, for example `en` or `pt-BR`.
    - `available_languages` LanguageTag[], required: Languages this version contains, without their text.
    - `created_at` string, date-time, nullable, required: When the version was created. Null for a built-in template's synthetic version.
    - `published_at` string, date-time, nullable, required: When the version was published. Null for the draft and for a built-in template's synthetic version.
  - `next_cursor` string, nullable, required: Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
  - `prev_cursor` string, nullable, required: Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
  - `refresh_cursor` string, nullable, required: Refresh anchor, the first row of this response. Pass back as `ending_before` to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-`null` whenever `data` is non-empty; `null` only on an empty page. Distinct from `prev_cursor`.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)