# Place a section

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

Put a section on a page of a draft, either one your account already has or a new one.

Send section_id to place a section that already exists, or name to create a new one and place it in the same request. Send exactly one of the two. A section is reusable and belongs to your account rather than to a template, so the same one can sit in several templates and in several versions of one template, at a different place each time.

A new section can only be created on a draft. On a published version the request is refused as invalid on version, and nothing is created.

What is placed is a precise version of the section. Say which with section_version_number, or say nothing and the published version is used. That is what stops a change made through one template reaching another: a placement names a version, not a section.

Where it sits and what it is headed here belong to the placement rather than to the section, so overriding the title changes this template and nothing else. Name a page or leave it out to land on the first one.

## 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.
- `section_id` (uuid, optional): The section to place. Required when name is absent, refused alongside it. One belonging to somebody else is refused as invalid, and so is one already on this version.
- `name` (string, optional): The name of a new section to create and place. Required when section_id is absent, refused alongside it. At most 255 characters.
- `icon` (string, optional): The icon of a new section, only with name. One of profile, people, note, relationship, family, timeline, calendar, reminder, tasks, memory, journal, file, mail, phone, place, home, briefcase, organization, graduation, health, activity, ball, food, gift, pet, plane, globe, book, music, coin, car, target, tag, heart, star, lock, layers.
- `colour` (string, optional): The colour of a new section, only with name. One of #3f5fd0, #4f8a49, #9a6a24, #9a3f2b, #6b4fa8, #2f7f86, #a8447a, #4a4a52.
- `section_version_number` (integer, optional): Which version of the section to place, only with section_id. The published one when absent. A version that is no longer offered is refused.
- `page_id` (uuid, optional): The page to place it on. The first page of the version when absent.
- `title_override` (string, optional): What to head the block here. The name of the section when absent.
- `is_collapsed_by_default` (boolean, optional): Whether the block starts folded shut. False when absent.

## Returns

The placement that was created, placed last on its page.

- `data` (object): The placement.
- `data.type` (string): Always structure_version_section. 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.position` (integer): Where the block sits on its page, counting from 1 again on each page.
- `data.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.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.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.section_name` (string): What the section is called in the section library.
- `data.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.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.is_collapsed_by_default` (boolean): Whether the block starts folded shut when somebody opens the record.
- `data.attributes.fields` (array): What the section collects. Empty here, since these endpoints answer with the placement rather than with the section contents. Read the version to get the whole structure.

## 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/4/sections \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "section_id": "d5e8c012-9a34-4b76-8f21-3e7c5a0b1d94",
      "title_override": "Where they live"
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/templates/7b1c4e92-3d58-4f07-9a26-8c5b0e14d3af/versions/4/sections', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    section_id: 'd5e8c012-9a34-4b76-8f21-3e7c5a0b1d94',
    title_override: 'Where they live',
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/templates/7b1c4e92-3d58-4f07-9a26-8c5b0e14d3af/versions/4/sections', [
    'section_id' => 'd5e8c012-9a34-4b76-8f21-3e7c5a0b1d94',
    'title_override' => 'Where they live',
]);
```

## Response

`201`

```json
{
    "data": {
        "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": []
        }
    }
}
```
