---
title: Personas
description: Manage persona variable sets that are injected into test runs.
---

# Personas

A Persona represents the account and role used for a browser test. It has a name, an optional description of up to 2,000 characters, variables, and saved session connections. Connect it to one or more [Environments](/api/environments) in the same project. Persona variables apply only to that Persona. At execution, the selected Environment supplies shared defaults and Persona values override matching keys.

Sensitive variable values are encrypted at rest and never returned by the API after creation. Plain values are returned in detail reads. Describe the role and intended tasks without putting credentials in the description.

Saved sessions live in the project library. A Persona can connect one account per domain; separate Personas can use different accounts for the same domain. Session capture, health settings and connections are managed in the app. Expired login blocks execution until repaired.

The former Environment variable endpoints are now Persona endpoints, without compatibility aliases. Existing variable sets and sessions migrate to Personas with their IDs preserved. Each gains a same-named Environment group.

## The persona object

```json
{
  "id": "018edddd-abcd-7000-8000-abc123456789",
  "workspaceId": "018e1234-abcd-7000-8000-abc123456789",
  "projectId": "018e5678-abcd-7000-8000-abc123456789",
  "name": "Staging",
  "variables": [
    {
      "id": "018eeeee-abcd-7000-8000-abc123456789",
      "key": "BASE_URL",
      "isSensitive": false
    },
    {
      "id": "018effff-abcd-7000-8000-abc123456789",
      "key": "ADMIN_PASSWORD",
      "isSensitive": true
    }
  ],
  "createdAt": "2026-04-01T08:00:00.000Z",
  "updatedAt": "2026-05-20T12:00:00.000Z"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | UUID | Unique identifier |
| `workspaceId` | UUID | Workspace this persona belongs to |
| `projectId` | UUID | Project this persona belongs to |
| `name` | string | Display name — must be unique per project |
| `description` | string or null | Role and intended usage, maximum 2,000 characters |
| `variables` | array | List of variable metadata (values are not returned) |
| `variables[].key` | string | Variable name |
| `variables[].isSensitive` | boolean | Whether the value is encrypted; sensitive values are never returned |
| `createdAt` | ISO 8601 | Creation timestamp |
| `updatedAt` | ISO 8601 | Last updated timestamp |

---

## List personas

<ApiPlayground
  method="GET"
  path="/v1/projects/:projectId/personas"
  scope="read"
  pathParams={[{ name: "projectId", type: "UUID", required: true, placeholder: "018e5678-abcd-7000-8000-abc123456789", description: "Project ID" }]}
/>

<ParamFields label="Path parameters">
  <ParamField name="projectId" type="UUID" required>Project ID</ParamField>
</ParamFields>

<Tabs items={["curl", "Python", "TypeScript"]}>
<Tab value="curl">

```bash
curl "https://api.smoketest.sh/v1/projects/018e5678-abcd-7000-8000-abc123456789/personas" \
  -H "Authorization: Bearer $SMOKETEST_API_KEY"
```

</Tab>
<Tab value="Python">

```python
envs = client.get(
    "/v1/projects/018e5678-abcd-7000-8000-abc123456789/personas"
).raise_for_status().json()
```

</Tab>
<Tab value="TypeScript">

```typescript
const res = await fetch(
  "https://api.smoketest.sh/v1/projects/018e5678-abcd-7000-8000-abc123456789/personas",
  { headers: { Authorization: "Bearer smkt_a1b2c3d4e5f6..." } },
);
const envs = await res.json();
```

</Tab>
</Tabs>

**Sample response**

```json
[
  {
    "id": "018edddd-abcd-7000-8000-abc123456789",
    "workspaceId": "018e1234-abcd-7000-8000-abc123456789",
    "projectId": "018e5678-abcd-7000-8000-abc123456789",
    "name": "Staging",
    "variables": [
      { "id": "018eeeee-abcd-7000-8000-abc123456789", "key": "BASE_URL", "isSensitive": false },
      { "id": "018effff-abcd-7000-8000-abc123456789", "key": "ADMIN_PASSWORD", "isSensitive": true }
    ],
    "createdAt": "2026-04-01T08:00:00.000Z",
    "updatedAt": "2026-05-20T12:00:00.000Z"
  }
]
```

---

## Create a Persona

<ApiPlayground
  method="POST"
  path="/v1/projects/:projectId/personas"
  scope="write"
  pathParams={[{ name: "projectId", type: "UUID", required: true, placeholder: "018e5678-abcd-7000-8000-abc123456789", description: "Project ID" }]}
  bodyParams={[
    { name: "description", type: "string", required: false, description: "Role and intended usage, up to 2,000 characters" },
    { name: "name", type: "string", required: true, placeholder: "Staging", description: "Display name, unique within the project" },
  ]}
/>

<ParamFields label="Path parameters">
  <ParamField name="projectId" type="UUID" required>Project ID</ParamField>
</ParamFields>

<ParamFields label="Body">
  <ParamField name="name" type="string" required>Display name, unique within the project</ParamField>
  <ParamField name="variables" type="array" required>Variable definitions</ParamField>
  <ParamField name="variables[].key" type="string" required>Variable name</ParamField>
  <ParamField name="variables[].isSensitive" type="boolean" required>Mark `true` for passwords, tokens, secrets</ParamField>
  <ParamField name="variables[].value" type="string">Variable value; omit to create a blank placeholder</ParamField>
</ParamFields>

<Tabs items={["curl", "Python", "TypeScript"]}>
<Tab value="curl">

```bash
curl -X POST "https://api.smoketest.sh/v1/projects/018e5678-abcd-7000-8000-abc123456789/personas" \
  -H "Authorization: Bearer $SMOKETEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Staging",
    "variables": [
      { "key": "BASE_URL", "isSensitive": false, "value": "https://staging.acme.com" },
      { "key": "ADMIN_PASSWORD", "isSensitive": true, "value": "s3cr3t!" }
    ]
  }'
```

</Tab>
<Tab value="Python">

```python
env = client.post(
    "/v1/projects/018e5678-abcd-7000-8000-abc123456789/personas",
    json={
        "name": "Staging",
        "variables": [
            {"key": "BASE_URL", "isSensitive": False, "value": "https://staging.acme.com"},
            {"key": "ADMIN_PASSWORD", "isSensitive": True, "value": "s3cr3t!"},
        ],
    },
).raise_for_status().json()
```

</Tab>
<Tab value="TypeScript">

```typescript
const res = await fetch(
  "https://api.smoketest.sh/v1/projects/018e5678-abcd-7000-8000-abc123456789/personas",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer smkt_a1b2c3d4e5f6...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Staging",
      variables: [
        { key: "BASE_URL", isSensitive: false, value: "https://staging.acme.com" },
        { key: "ADMIN_PASSWORD", isSensitive: true, value: "s3cr3t!" },
      ],
    }),
  },
);
const env = await res.json();
```

</Tab>
</Tabs>

---

## Get a Persona

<ApiPlayground
  method="GET"
  path="/v1/personas/:id"
  scope="read"
  pathParams={[{ name: "id", type: "UUID", required: true, placeholder: "018edddd-abcd-7000-8000-abc123456789", description: "Persona ID" }]}
/>

<ParamFields label="Path parameters">
  <ParamField name="id" type="UUID" required>Persona ID</ParamField>
</ParamFields>

<Tabs items={["curl", "Python", "TypeScript"]}>
<Tab value="curl">

```bash
curl https://api.smoketest.sh/v1/personas/018edddd-abcd-7000-8000-abc123456789 \
  -H "Authorization: Bearer $SMOKETEST_API_KEY"
```

</Tab>
<Tab value="Python">

```python
env = client.get(
    "/v1/personas/018edddd-abcd-7000-8000-abc123456789"
).raise_for_status().json()
```

</Tab>
<Tab value="TypeScript">

```typescript
const res = await fetch("https://api.smoketest.sh/v1/personas/018edddd-abcd-7000-8000-abc123456789", {
  headers: { Authorization: "Bearer smkt_a1b2c3d4e5f6..." },
});
const env = await res.json();
```

</Tab>
</Tabs>