# Get Persona - **Method:** `GET` - **Path:** `/api/v1/personas/{address}` - **Operation ID:** `get_persona` - **Tags:** personas One persona in full, by `id@version` or by `id` for its latest version: its goals, priors, tolerance, constraints, voice and verdict question - everything that drives how it behaves in a run. ## Effective servers - `https://api.saram.sh` Saram ## Authentication - **HTTPBearer**: HTTP bearer a Saram API key (`sk_saram__...`) or a person's AuthKit access token, as `Authorization: Bearer `. Both are told apart by shape and produce the same principal. ## Path parameters - **`address` (required)**: `string` ## Responses ### 200 Successful Response **Content type:** `application/json` schema: `Persona`, no additional properties A structured persona: a sampling strategy over the UI state space plus a tolerance function. Two kinds of fields: a structured core the run enforces and the dashboard diffs (`tolerance`, `constraints`, `action_policy`), and prose behavior fields the model reads (`backstory`, `vocabulary`, `facts`, `conversation`, `verdict_prompt`). Both drive what the persona does. `voice` affects narration only. - **`action_policy` (required)**: `object`, schema: `ActionPolicy`, no additional properties How the persona works a page: how much of it they read, what they work it with, whether they wander or head straight for the goal, and how they treat defaults, help and errors. Each value becomes a line of the persona's briefing. - **`exploration` (required)**: `string`, possible values: `"explores", "beeline"` Schema: `Exploration`. Wanders vs. heads straight for the goal - **`input` (required)**: `string`, possible values: `"mouse", "keyboard", "touch"` Schema: `Input`. What the persona works the page with. `mouse`: a computer with a mouse and a keyboard. `keyboard`: tabs between fields and presses Enter rather than reach for the mouse. `touch`: a phone, tapping and swiping. This shapes the persona's habits; whether the browser itself is a touch device is `constraints.device`. - **`reading` (required)**: `string`, possible values: `"reads", "skims", "ignores"` Schema: `Reading`. How much on-screen text they consume - **`error_response`**: `string | null`, possible values: `"retry_same", "retry_different", "back_out", "abandon"` Schema: `ErrorResponse`. First reaction to an error - **`help_seeking`**: `string | null`, possible values: `"never", "after_error", "eager"` Schema: `HelpSeeking`. Uses tooltips, help links, search - **`trust_defaults`**: `string | null`, possible values: `"low", "medium", "high"` Schema: `TrustDefaults`. Accepts prefilled/default choices vs. checks everything - **`constraints` (required)**: `object`, schema: `Constraints`, no additional properties The browser the persona uses: the kind of device, the screen size, the connection, the language, accessibility needs and the signed-in state they start in. Most of these set up the browser session rather than the persona's briefing. A replay of an issue runs with the same ones, and the issue lists them in `preconditions`. - **`device` (required)**: `string`, possible values: `"desktop", "mobile", "tablet"` Schema: `Device`. The kind of device the browser presents as. `mobile` and `tablet` open a mobile, touch-enabled browser; `desktop` a desktop one. The screen size is `viewport`, set separately. - **`viewport` (required)**: `string`, pattern: `^[0-9]+x[0-9]+$` - **`accessibility`**: `array | null` **Items:** `string`, possible values: `"screen_reader", "keyboard_only", "low_vision", "reduced_motion", "color_blind"` Schema: `AccessibilityEnum`. One accessibility need the persona has. - **`auth_state`**: `string | null`, possible values: `"anonymous", "new_user", "returning_user", "admin"`, default: `"anonymous"` Schema: `AuthState`. The kind of visitor the persona arrives as: `anonymous` (the default), a `new_user`, a `returning_user` or an `admin`. Descriptive, and listed in each issue's `preconditions`; it signs nobody in. A session is signed in by the account it is handed from the run spec's `target.seed.accounts`. - **`locale`**: `string | null`, default: `"en-US"` - **`network`**: `string | null`, possible values: `"fast", "regular_4g", "slow_3g", "offline_flaky"`, default: `"fast"` Schema: `Network`. The connection the browser runs on. `fast` (the default): not throttled. `regular_4g` and `slow_3g`: bandwidth limited and latency added, like those mobile connections. `offline_flaky` is not supported yet, and a session that asks for it does not start. - **`goals` (required)**: `object`, schema: `Goals`, no additional properties What the persona wants out of the visit, in their own terms: the `primary` goal, anything `secondary` they also want if they get that far, and how much they want it (`intensity`). All three go into the persona's briefing beside the mission's goal; what counts as success for the run is the mission's `success_criteria`. - **`intensity` (required)**: `string`, possible values: `"low", "medium", "high"` Schema: `Intensity`. How much they want it; interacts with tolerance - **`primary` (required)**: `string` - **`secondary`**: `(array of string) | null` - **`id` (required)**: `string`, pattern: `^[a-z0-9_]+$` - **`priors` (required)**: `object`, schema: `Priors`, no additional properties What the persona knows before they arrive: how well they know this product, the language of its industry and technology in general, the expectations they bring from other products, and what they were told beforehand. Each goes into the persona's briefing and shapes what they understand, expect and notice. - **`domain_literacy`**: `string | null`, possible values: `"low", "medium", "high"` Schema: `DomainLiteracy`. How fluent the persona is in the language of the product's industry. `low`: does not know its terms and does not pretend to. `medium`: knows enough to follow along. `high`: fluent, and notices when a term is used loosely. - **`mental_models`**: `(array of string) | null` - **`prior_instructions`**: `(array of string) | null` - **`product_familiarity`**: `string | null`, possible values: `"none", "low", "medium", "high"` Schema: `ProductFamiliarity`. How well the persona knows this product before the session. `none`: never used it and not sure what it is. `low`: seen it once and remembers almost nothing. `medium`: knows this kind of product, not this one in particular. `high`: knows it well and expects things where they left them. - **`technical_literacy`**: `string | null`, possible values: `"low", "medium", "high"` Schema: `TechnicalLiteracy`. How comfortable the persona is with technology. `low`: not technical; keys, tokens and APIs mean nothing to them. `medium`: finds their way around an app's settings without being technical. `high`: technical, and notices when a key or a token is handled badly. - **`tolerance` (required)**: `object`, schema: `Tolerance`, no additional properties How much the persona puts up with before giving up. Saram counts, step by step, the steps without visible progress, the errors and slow responses, and the moments with no clear next action, and ends the session `abandoned` the moment one crosses its threshold here; the model playing the persona cannot argue with the count. The persona is also told these limits in their own terms. - **`error_threshold` (required)**: `integer`, minimum: `0` - **`patience_steps` (required)**: `integer`, minimum: `1` - **`abandon_behavior`**: `string | null`, possible values: `"silent", "narrates_reason"`, default: `"narrates_reason"` Schema: `AbandonBehavior`. What the persona's diary says when they give up, on one task or on the whole session. `narrates_reason` (the default): they say why before they stop. `silent`: they simply stop. - **`attempts_per_subtask`**: `integer | null`, minimum: `1` - **`confusion_threshold`**: `integer | null`, minimum: `1` - **`latency_sensitivity_ms`**: `integer | null`, minimum: `0` - **`version` (required)**: `integer`, minimum: `1` - **`backstory`**: `string | null` - **`conversation`**: `object | null`, schema: `Conversation`, no additional properties How the persona talks to an in-product assistant or chat surface. Matters when the target is itself an AI product. - **`asks_before_hunting`**: `boolean | null` - **`phrasing`**: `string | null`, possible values: `"plain_speech", "commands", "mixed"` Schema: `Phrasing`. Asks like they would ask a person, vs. writes instructions - **`pushes_back_on_generic`**: `boolean | null` - **`facts`**: `object | null` **Additional properties:** `string` - **`name`**: `string | null` - **`pack`**: `string | null` - **`provenance`**: `object | null`, schema: `Provenance`, no additional properties How this persona was grounded. Generators fill this. - **`generated_at`**: `string | null`, format: `date-time` - **`generator`**: `string | null` - **`notes`**: `string | null` - **`sources`**: `(array of string) | null` - **`tags`**: `(array of string) | null` - **`verdict_prompt`**: `string | null` - **`vocabulary`**: `object | null`, schema: `Vocabulary`, no additional properties Terms the persona does and does not understand. More specific than the literacy enums in `priors`; the renderer tells the actor to say so when an unknown term appears rather than guess. - **`knows`**: `(array of string) | null` - **`unknown`**: `(array of string) | null` - **`voice`**: `object | null`, schema: `Voice`, no additional properties Narration style only. It never influences what the persona does. - **`style`**: `string | null` - **`verbosity`**: `string | null`, possible values: `"terse", "normal", "verbose"` Schema: `Verbosity`. How long the persona's diary entries run. `terse`: short. `normal`: as much as the moment deserves. `verbose`: in full, with the detail they noticed. **Example:** ```json { "id": "", "version": 1, "name": "", "pack": "", "tags": [ "" ], "backstory": "", "vocabulary": { "knows": [ "" ], "unknown": [ "" ] }, "facts": { "additionalProperty": "" }, "conversation": { "phrasing": "plain_speech", "asks_before_hunting": true, "pushes_back_on_generic": true }, "verdict_prompt": "", "goals": { "primary": "", "secondary": [ "" ], "intensity": "low" }, "priors": { "product_familiarity": "none", "domain_literacy": "low", "technical_literacy": "low", "mental_models": [ "" ], "prior_instructions": [ "" ] }, "action_policy": { "reading": "reads", "input": "mouse", "exploration": "explores", "trust_defaults": "low", "help_seeking": "never", "error_response": "retry_same" }, "tolerance": { "patience_steps": 1, "error_threshold": 0, "latency_sensitivity_ms": 0, "confusion_threshold": 1, "attempts_per_subtask": 1, "abandon_behavior": "narrates_reason" }, "constraints": { "device": "desktop", "viewport": "", "network": "fast", "accessibility": [ "screen_reader" ], "locale": "en-US", "auth_state": "anonymous" }, "voice": { "style": "", "verbosity": "terse" }, "provenance": { "generator": "", "sources": [ "" ], "generated_at": "", "notes": "" } } ``` ### 403 the API key lacks the required scope ### 422 Validation Error **Content type:** `application/json` schema: `HTTPValidationError` - **`detail`**: `array` **Items:** schema: `ValidationError` - **`loc` (required)**: `array of (string | integer)` - **`msg` (required)**: `string` - **`type` (required)**: `string` - **`ctx`**: `object` - **`input`**: `any` **Example:** ```json { "detail": [ { "loc": [ "" ], "msg": "", "type": "", "input": null, "ctx": {} } ] } ``` ## Schemas ### AbandonBehavior **Type:** `string`, possible values: `"silent", "narrates_reason"` What the persona's diary says when they give up, on one task or on the whole session. `narrates_reason` (the default): they say why before they stop. `silent`: they simply stop. ### AccessibilityEnum **Type:** `string`, possible values: `"screen_reader", "keyboard_only", "low_vision", "reduced_motion", "color_blind"` One accessibility need the persona has. - `ActionPolicy` — shown above. ### AuthState **Type:** `string`, possible values: `"anonymous", "new_user", "returning_user", "admin"` The kind of visitor the persona arrives as: `anonymous` (the default), a `new_user`, a `returning_user` or an `admin`. Descriptive, and listed in each issue's `preconditions`; it signs nobody in. A session is signed in by the account it is handed from the run spec's `target.seed.accounts`. - `Constraints` — shown above. - `Conversation` — shown above. ### Device **Type:** `string`, possible values: `"desktop", "mobile", "tablet"` The kind of device the browser presents as. `mobile` and `tablet` open a mobile, touch-enabled browser; `desktop` a desktop one. The screen size is `viewport`, set separately. ### DomainLiteracy **Type:** `string`, possible values: `"low", "medium", "high"` How fluent the persona is in the language of the product's industry. `low`: does not know its terms and does not pretend to. `medium`: knows enough to follow along. `high`: fluent, and notices when a term is used loosely. ### ErrorResponse **Type:** `string`, possible values: `"retry_same", "retry_different", "back_out", "abandon"` First reaction to an error ### Exploration **Type:** `string`, possible values: `"explores", "beeline"` Wanders vs. heads straight for the goal - `Goals` — shown above. - `HTTPValidationError` — shown above. ### HelpSeeking **Type:** `string`, possible values: `"never", "after_error", "eager"` Uses tooltips, help links, search ### Input **Type:** `string`, possible values: `"mouse", "keyboard", "touch"` What the persona works the page with. `mouse`: a computer with a mouse and a keyboard. `keyboard`: tabs between fields and presses Enter rather than reach for the mouse. `touch`: a phone, tapping and swiping. This shapes the persona's habits; whether the browser itself is a touch device is `constraints.device`. ### Intensity **Type:** `string`, possible values: `"low", "medium", "high"` How much they want it; interacts with tolerance ### Network **Type:** `string`, possible values: `"fast", "regular_4g", "slow_3g", "offline_flaky"` The connection the browser runs on. `fast` (the default): not throttled. `regular_4g` and `slow_3g`: bandwidth limited and latency added, like those mobile connections. `offline_flaky` is not supported yet, and a session that asks for it does not start. - `Persona` — shown above. ### Phrasing **Type:** `string`, possible values: `"plain_speech", "commands", "mixed"` Asks like they would ask a person, vs. writes instructions - `Priors` — shown above. ### ProductFamiliarity **Type:** `string`, possible values: `"none", "low", "medium", "high"` How well the persona knows this product before the session. `none`: never used it and not sure what it is. `low`: seen it once and remembers almost nothing. `medium`: knows this kind of product, not this one in particular. `high`: knows it well and expects things where they left them. - `Provenance` — shown above. ### Reading **Type:** `string`, possible values: `"reads", "skims", "ignores"` How much on-screen text they consume ### TechnicalLiteracy **Type:** `string`, possible values: `"low", "medium", "high"` How comfortable the persona is with technology. `low`: not technical; keys, tokens and APIs mean nothing to them. `medium`: finds their way around an app's settings without being technical. `high`: technical, and notices when a key or a token is handled badly. - `Tolerance` — shown above. ### TrustDefaults **Type:** `string`, possible values: `"low", "medium", "high"` Accepts prefilled/default choices vs. checks everything - `ValidationError` — shown above. ### Verbosity **Type:** `string`, possible values: `"terse", "normal", "verbose"` How long the persona's diary entries run. `terse`: short. `normal`: as much as the moment deserves. `verbose`: in full, with the detail they noticed. - `Vocabulary` — shown above. - `Voice` — shown above.