# Get a template version

`GET /api/v1/templates/{template}/versions/{version}`

Retrieve one version and everything it is made of: its pages, the sections placed on each, and the fields of each section.

This is the endpoint that tells you what a record means. A record names the version it sits on, and this answers with the structure that version froze, so a client can render the record without guessing what any of its values are for.

The whole structure comes back in one answer rather than a page at a time. A structure is one document, and splitting it would make it unreadable.

The version is named by its number within its template, which is the number the version history shows, and not by a row id. Version 3 of one template and version 3 of another are different things reached through different templates.

A section is placed rather than owned. The same section can sit in several templates, and each placement names a precise version of it, which is what stops a change made through one template reaching another.

This endpoint also answers QUERY, with the same parameters sent in the request body. [How QUERY works](https://my.monicahq.com/docs/api/query-method).

## Path parameters

- `template` (uuid, required): The id of the template. A path that is not a uuid answers 404 without a query being run, so neither the slug nor a sequential number reaches anything here.
- `version` (integer, required): The number of the version within its template, counting from 1, which is the number shown in the version history and the number a change note refers to. It is not a row id, so version 1 of one template and version 1 of another are different things reached through different templates.

## Returns

A version object carrying its pages, their sections and their fields. A number the template does not have answers 404, and so does a template belonging to somebody else.

- `data` (object): The version.
- `data.type` (string): Always structure_version. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.
- `data.id` (string): The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.
- `data.attributes` (object): Everything the record holds.
- `data.attributes.version_number` (integer): Which version this is within its template, counting from 1. It is what the address of this version takes, and what a change note refers to.
- `data.attributes.status` (string): Either draft or published. A draft is still being designed and may be changed freely. A published version is frozen and never changes again, and stays published after a later version replaces it, so read published_version_number on the template to know which one a new record is put on.
- `data.attributes.change_note` (string): What changed since the version before, written when this one was published, or null on a draft and on the first version of a template. It is what somebody deciding whether to move their records reads.
- `data.attributes.published_at` (timestamp): When the version was frozen, as a count of seconds, or null while it is a draft.
- `data.attributes.retired_at` (timestamp): Always null. Publishing a later version does not retire the one it replaces, because the records still on it go on working exactly as they did.
- `data.attributes.record_count` (integer): How many records point at this precise version. A record follows the version it was put on until somebody moves it deliberately, so a retired version keeps a count above zero for as long as anything is still on it.
- `data.attributes.previous_version_number` (integer): The number of the version this one was started from, or null on the first version of a template.
- `data.attributes.created_at` (timestamp): When the version was started, as a count of seconds.
- `data.attributes.updated_at` (timestamp): When it last changed, as a count of seconds. Equal to created_at until it first changes. A published version never changes, so this stops moving at publication.
- `data.attributes.pages` (array): The tabs the version is divided into, in the order they are shown. Present only when one version is read on its own, never in the list.
- `data.attributes.pages[]` (object): One page.
- `data.attributes.pages[].type` (string): Always structure_version_page. It names the kind of record, so a caller holding several kinds can tell them apart.
- `data.attributes.pages[].id` (string): The id of the page, as a string even when it reads as a number.
- `data.attributes.pages[].attributes` (object): Everything the page holds.
- `data.attributes.pages[].attributes.key` (string): How the page is addressed in a browser link. It is settled when the page is added and survives every rename.
- `data.attributes.pages[].attributes.label` (string): What the tab says. A page the product supplied answers with the label translated into your language.
- `data.attributes.pages[].attributes.position` (integer): Where the tab sits, counting from 1.
- `data.attributes.pages[].attributes.sections` (array): The blocks placed on this page, in the order they are shown.
- `data.attributes.pages[].attributes.sections[]` (object): One placement.
- `data.attributes.pages[].attributes.sections[].type` (string): Always structure_version_section. It names the kind of record, so a caller holding several kinds can tell them apart.
- `data.attributes.pages[].attributes.sections[].id` (string): The id of the placement, as a string even when it reads as a number.
- `data.attributes.pages[].attributes.sections[].attributes` (object): Everything the placement holds.
- `data.attributes.pages[].attributes.sections[].attributes.position` (integer): Where the block sits on its page, counting from 1 again on each page.
- `data.attributes.pages[].attributes.sections[].attributes.title` (string): What the block is headed: the override when there is one, and the name of the section otherwise. It is what to show a reader.
- `data.attributes.pages[].attributes.sections[].attributes.title_override` (string): The heading chosen for this placement alone, or null when the section name is used. What a section is called here belongs to the assembly rather than to the section.
- `data.attributes.pages[].attributes.sections[].attributes.section_id` (string): The id of the reusable section behind the placement. The same section may appear in several templates and in several versions of one template.
- `data.attributes.pages[].attributes.sections[].attributes.section_name` (string): What the section is called in the section library.
- `data.attributes.pages[].attributes.sections[].attributes.section_version_number` (integer): Which version of the section is placed here. A placement names a version and not a section, which is what stops a change made through another template reaching this one.
- `data.attributes.pages[].attributes.sections[].attributes.section_version_status` (string): One of draft, published or retired, for the section version rather than the template version. A template version cannot be published while a section it carries is still a draft.
- `data.attributes.pages[].attributes.sections[].attributes.is_collapsed_by_default` (boolean): Whether the block starts folded shut when somebody opens the record.
- `data.attributes.pages[].attributes.sections[].attributes.fields` (array): What the section collects, in the order it is shown. Fields belong to the section version, never to the section, which is what makes freezing reach all the way down.
- `data.attributes.pages[].attributes.sections[].attributes.fields[]` (object): One field.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].type` (string): Always field. It names the kind of record, so a caller holding several kinds can tell them apart.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].id` (string): The id of the field, as a string even when it reads as a number.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes` (object): Everything the field holds.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.key` (string): How the field is named in an import or an export, settled when the field is added.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.type` (string): What kind of thing the field holds: one of text, textarea, number, boolean, url, email, phone, select, multiselect, radio, date, recurring_date, duration (a whole number of minutes), relation, file, image, avatar, address, repeater, divider, heading or help. The last three carry no value and are there to lay the form out.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.label` (string): What the field is called on the form.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.help_text` (string): A sentence shown under the field, or null when there is none.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.placeholder` (string): What the empty box shows as an example, or null.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.position` (integer): Where the field sits in its section, counting from 1.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.is_required` (boolean): Whether the record refuses to save without it.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.is_sensitive` (boolean): Whether the value is hidden until somebody asks to see it.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.is_highlighted` (boolean): Whether the value is repeated at the top of the record.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.is_unique` (boolean): Whether two records of this template may hold the same value.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.is_identifying` (boolean): Whether two records sharing this value are likely the same record, so the pair is proposed as a duplicate. Not the same as unique: a household can legitimately share one telephone number, and proposing a pair is right where refusing the value would be wrong.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.is_repeatable` (boolean): Whether the field holds several values rather than one. It follows from the type and is settled when the field is added.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.repeat_min` (integer): The fewest repetitions allowed, or null when there is no floor.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.repeat_max` (integer): The most repetitions allowed, or null when there is no ceiling.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.repetition_order` (string): How several values are ordered against each other, or null when the field holds one.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.options` (object): Settings belonging to this kind of field alone, or null. What it holds depends on the type.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.validation` (object): Extra rules a value has to satisfy, or null.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.default_value` (object): What the field starts filled with, or null.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.relation_target` (string): What a relation field points at, or null when the field is not a relation. It is settled when the field is added.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.created_at` (timestamp): When the field was added, as a count of seconds since 1970.
- `data.attributes.pages[].attributes.sections[].attributes.fields[].attributes.updated_at` (timestamp): When it last changed, as a count of seconds, or null.
- `data.links` (object): Where to find this record.
- `data.links.self` (string): The absolute address this record is read from.

## Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in `X-RateLimit-Remaining`.

## Request

```sh
curl https://my.monicahq.com/api/v1/templates/7b1c4e92-3d58-4f07-9a26-8c5b0e14d3af/versions/3 \
  -H "Authorization: Bearer $MONICA_TOKEN"
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/templates/7b1c4e92-3d58-4f07-9a26-8c5b0e14d3af/versions/3', {
  headers: { Authorization: `Bearer ${token}` },
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->get('https://my.monicahq.com/api/v1/templates/7b1c4e92-3d58-4f07-9a26-8c5b0e14d3af/versions/3');
```

## Response

`200`

```json
{
    "data": {
        "type": "structure_version",
        "id": "312",
        "attributes": {
            "version_number": 3,
            "status": "published",
            "change_note": "Added the medical page.",
            "published_at": 1756339200,
            "retired_at": null,
            "record_count": 84,
            "previous_version_number": 2,
            "created_at": 1756335600,
            "updated_at": 1756339200,
            "pages": [
                {
                    "type": "structure_version_page",
                    "id": "a1f7b3c8-6e42-4d09-8b57-1c9e0f2a4d36",
                    "attributes": {
                        "key": "general",
                        "label": "General",
                        "position": 1,
                        "sections": [
                            {
                                "type": "structure_version_section",
                                "id": "904",
                                "attributes": {
                                    "position": 1,
                                    "title": "Where they live",
                                    "title_override": "Where they live",
                                    "section_id": "d5e8c012-9a34-4b76-8f21-3e7c5a0b1d94",
                                    "section_name": "Address",
                                    "section_version_number": 2,
                                    "section_version_status": "published",
                                    "is_collapsed_by_default": false,
                                    "fields": [
                                        {
                                            "type": "field",
                                            "id": "5521",
                                            "attributes": {
                                                "key": "street",
                                                "type": "text",
                                                "label": "Street",
                                                "help_text": null,
                                                "placeholder": "221B Baker Street",
                                                "position": 1,
                                                "is_required": false,
                                                "is_sensitive": false,
                                                "is_highlighted": false,
                                                "is_unique": false,
                                                "is_identifying": false,
                                                "is_repeatable": false,
                                                "repeat_min": null,
                                                "repeat_max": null,
                                                "repetition_order": null,
                                                "options": null,
                                                "validation": null,
                                                "default_value": null,
                                                "relation_target": null,
                                                "created_at": 1756335600,
                                                "updated_at": 1756335600
                                            }
                                        }
                                    ]
                                }
                            }
                        ]
                    }
                }
            ]
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/templates/7b1c4e92-3d58-4f07-9a26-8c5b0e14d3af/versions/3"
        }
    }
}
```
