# Editor Session

## Create a new session

<mark style="color:green;">`POST`</mark> `https://api.usestencil.com/v1/editor/sessions`

### **Request Body**

<table><thead><tr><th width="154.76904296875">Name</th><th width="110.35498046875"></th><th width="146.3775634765625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>Required</td><td>string</td><td>Name of the session</td></tr><tr><td><code>expires</code></td><td>Required</td><td>integer</td><td>Time till expire. In seconds.</td></tr><tr><td><code>template_id</code></td><td>Required</td><td>uuid</td><td>The template to give access to</td></tr><tr><td><code>permissions</code></td><td>Optional</td><td>object</td><td>See <code>permission</code> object, <a data-mention href="#permission-object">#permission-object</a></td></tr></tbody></table>

#### Permission object

<table><thead><tr><th width="156.4305419921875">Name</th><th width="108.14056396484375"></th><th width="111.68829345703125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>layers</code></td><td>Required</td><td>object</td><td><code>layer</code> object</td></tr></tbody></table>

#### Layer object

<table><thead><tr><th width="106.08941650390625">Name</th><th width="100.7586669921875"></th><th width="194.5399169921875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>actions</code></td><td>Optional</td><td>array of string</td><td><strong>Set the default actions for all layers.</strong> Value can be combination of <code>"create"</code>, <code>"edit"</code>, and <code>"delete"</code></td></tr><tr><td><code>fields</code></td><td>Optional</td><td>array of <code>field</code> object</td><td>Override default action for specific layer. See <code>field</code> object.</td></tr></tbody></table>

#### Field object

<table><thead><tr><th width="107.06768798828125">Name</th><th width="112.21270751953125"></th><th width="189.9765625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>Required</td><td>string</td><td>Name of the layer</td></tr><tr><td><code>actions</code></td><td>Required</td><td>array of string</td><td>Value can be combination of <code>"create"</code>, <code>"edit"</code>, and <code>"delete"</code></td></tr></tbody></table>

#### Permission actions

Action can be combination of  `"create"`, `"edit"`, and `"delete"` .

<table><thead><tr><th width="102.61114501953125">Action</th><th>Effect</th></tr></thead><tbody><tr><td><code>create</code></td><td>When specified, user can create a new layer or duplicate an existing layer.</td></tr><tr><td><code>edit</code></td><td>When specified, user is allowed to make changes to the layer.</td></tr><tr><td><code>delete</code></td><td>When specified, user is allowed to delete the layer.</td></tr></tbody></table>

When you override the field, the permission set by the default permission is ignored.

#### Request body examples

{% tabs %}
{% tab title="Create with default permission" %}

```json
{
    "name": "Session 1",
    "template_id": "<template_id>",
    "expires": 60000
}
```

{% endtab %}

{% tab title="Create with custom permissions" %}

```json
{
    "name": "Session 1",
    "template_id": "<template_id>",
    "expires": 60000,
    "permissions": {
        "layers" {
            "actions": ["edit"],
            "fields": [
                {
                    "name": "image",
                    "actions": ["edit", "delete"]
                },
                {
                    "name": "description_text",
                    "actions": ["edit"]
                }               
            ]
        }
    }
}
```

{% endtab %}
{% endtabs %}

## Get a session

<mark style="color:green;">`GET`</mark> `https://api.usestencil.com/v1/editor/sessions/:session_id`

### Response body

{% tabs %}
{% tab title="200 (No permission set)" %}

```json
{
  "permissions": null,
  "token": "QFhV6HN7hv3nqPcnGhp2xo",
  "session_id": "daf35835-fd26-4503-8027-1bb59417be91",
  "expired_at": "2025-05-18T03:31:34Z",
  "session_url": "http://app.usestencil.com/editor/templates/f636ffa7-8761-4877-960b-cf5b97a41c6b/sessions/daf35835-fd26-4503-8027-1bb59417be91?token=QFhV6HN7hv3nqPcnGhp2xo"
}
```

{% endtab %}

{% tab title="200 (With custom permission)" %}

```json
{
  "permissions": {
    "layers": {
      "fields": [
        {
          "name": "field",
          "actions": [
            "create",
            "edit"
          ]
        }
      ],
      "actions": [
        "create",
        "edit",
        "delete"
      ]
    }
  },
  "token": "QFhV6HN7hv3nqPcnGhp2xo",
  "session_id": "daf35835-fd26-4503-8027-1bb59417be91",
  "expired_at": "2025-05-18T03:31:34Z",
  "session_url": "http://app.usestencil.com/editor/templates/f636ffa7-8761-4877-960b-cf5b97a41c6b/sessions/daf35835-fd26-4503-8027-1bb59417be91?token=QFhV6HN7hv3nqPcnGhp2xo"
}
```

{% endtab %}
{% endtabs %}