> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rhetoric.law/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Element session

Creates a new Element session.

This operation returns a session token that can be passed to an embedded Element
in the browser. The Element uses the token to make subsequent calls to Rhetoric
directly.

## Request

<ParamField body="customer_session_ref" type="string">
  Optional customer-provided session reference. You can use this to associate an
  Element session with your own internal session identifier.
</ParamField>

## Response

<ResponseField name="session_id" type="string">
  The session id.
</ResponseField>

<ResponseField name="browser_token" type="string">
  Browser-scoped bearer token. Pass this as the `Authorization` header for all
  subsequent Element calls made from the browser.
</ResponseField>

<ResponseField name="expires_at" type="string">
  Session expiration timestamp, in RFC 3339 format. Sessions expire two hours
  after creation.
</ResponseField>

<ResponseField name="state_token" type="string">
  Initial state token for the session.
</ResponseField>

<ResponseField name="session_status" type="string">
  Current session lifecycle state: `open` or `submitted`.
</ResponseField>

<ResponseField name="form" type="object">
  Backend-rendered form view for the first section of the flow.
</ResponseField>

## Errors

This operation has no application errors.

## Example

```shell Request theme={null}
curl -X POST https://api.rhetoric.law/create-element-session \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "customer_session_ref": "acme-session-1234" }'
```

```json Response theme={null}
{
  "result": "ok",
  "session_id": "ses_8f2c1a",
  "browser_token": "brt_9c1e...",
  "expires_at": "2026-08-04T21:00:00Z",
  "state_token": "stt_1a2b3c",
  "session_status": "open",
  "form": { ... }
}
```