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

string

Optional customer-provided session reference. You can use this to associate an Element session with your own internal session identifier.

Response

string

The session id.

string

Browser-scoped bearer token. Pass this as the Authorization header for all subsequent Element calls made from the browser.

string

Session expiration timestamp, in RFC 3339 format. Sessions expire two hours after creation.

string

Initial state token for the session.

string

Current session lifecycle state: open or submitted.

object

Backend-rendered form view for the first section of the flow.

Errors

This operation has no application errors.

Example

Request

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" }'

Response

{
  "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": { ... }
}

​Request

​Response

​Errors

​Example

Request

Response

Errors

Example