# Open a draft

`POST /api/v1/templates/{template}/versions`

Start a draft of a template, copied from the version it is published at.

A published version never changes again, so changing a structure means opening a draft beside it and working there. The draft arrives carrying a copy of the pages, the section placements and the fields of the version it came from, and the published version goes on serving every record exactly as before until you publish.

A template has at most one draft at a time. Asking again while one is open answers with that draft and 200 rather than starting a second, so a client that retries a request it is unsure about cannot end up with two.

The draft is copied from the published version when there is one, and from the newest version otherwise. A template with no version at all has nothing to copy and answers 404.

## 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.

## Returns

The draft, with 201 when it was started and 200 when one was already open. A template belonging to somebody else answers 404, and so does one with no version to copy.

- `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.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 \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN"
```

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

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

## Response

`201`

```json
{
    "data": {
        "type": "structure_version",
        "id": "318",
        "attributes": {
            "version_number": 4,
            "status": "draft",
            "change_note": null,
            "published_at": null,
            "retired_at": null,
            "record_count": 0,
            "previous_version_number": 3,
            "created_at": 1756425600,
            "updated_at": 1756425600
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/templates/7b1c4e92-3d58-4f07-9a26-8c5b0e14d3af/versions/4"
        }
    }
}
```
