Persona

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usewrit-app/json-schema/usewrit-app-persona-schema.json",
  "title": "Persona",
  "description": "The shaped persona wire form (cloud `PersonaResponse` parity). Secrets collapse to `has_*` booleans plus `linked_secrets` names; cloud-only columns (mailbox, relay minting, preferred agent) are always null locally. A vault-linked username (`{{vault:…}}` template) is surfaced as null here — the link appears in `linked_secrets` instead.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/writ-agent.yaml#/components/schemas/Persona",
  "type": "object",
  "required": [
    "id",
    "name",
    "description",
    "target_domain",
    "login_username",
    "has_password",
    "twofa_method",
    "has_totp_seed",
    "email_otp_mode",
    "mail_connection_id",
    "connected_mailbox",
    "relay_address",
    "relay_token",
    "relay_inbound_address",
    "relay_inbound_url",
    "has_fingerprint",
    "preferred_agent_id",
    "has_proxy",
    "proxy_lawful_use_ack_at",
    "is_active",
    "validation_status",
    "has_warm_session",
    "session_expires_at",
    "last_login_at",
    "last_used_at",
    "created_at",
    "updated_at",
    "linked_workflows",
    "linked_secrets"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "target_domain": {
      "type": [
        "string",
        "null"
      ]
    },
    "login_username": {
      "type": [
        "string",
        "null"
      ]
    },
    "has_password": {
      "type": "boolean"
    },
    "twofa_method": {
      "type": "string",
      "enum": [
        "none",
        "totp",
        "email_otp",
        "sms"
      ]
    },
    "has_totp_seed": {
      "type": "boolean"
    },
    "email_otp_mode": {
      "type": [
        "string",
        "null"
      ],
      "description": "`oauth_mailbox` | `relay` | null."
    },
    "mail_connection_id": {
      "type": "null",
      "description": "Cloud-only; always null locally."
    },
    "connected_mailbox": {
      "type": "null",
      "description": "Cloud-only; always null locally."
    },
    "relay_address": {
      "type": [
        "string",
        "null"
      ]
    },
    "relay_token": {
      "type": "null",
      "description": "Cloud-only; always null locally."
    },
    "relay_inbound_address": {
      "type": "null",
      "description": "Cloud-only; always null locally."
    },
    "relay_inbound_url": {
      "type": "null",
      "description": "Cloud-only; always null locally."
    },
    "has_fingerprint": {
      "type": "boolean"
    },
    "preferred_agent_id": {
      "type": "null",
      "description": "Cloud-only; always null locally."
    },
    "has_proxy": {
      "type": "boolean"
    },
    "proxy_lawful_use_ack_at": {
      "type": "null",
      "description": "Cloud-only; always null locally."
    },
    "is_active": {
      "type": "boolean"
    },
    "validation_status": {
      "type": "string"
    },
    "has_warm_session": {
      "type": "boolean"
    },
    "session_expires_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "last_login_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "last_used_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "linked_workflows": {
      "type": "array",
      "description": "Workflows pinned to this persona via `default_persona_id`.",
      "items": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "name": {
            "type": "string"
          }
        }
      }
    },
    "linked_secrets": {
      "type": "object",
      "description": "`{credential_field: vault secret base name}` for values stored as `{{vault:…}}` templates. Names only — never values.",
      "additionalProperties": {
        "type": "string"
      }
    }
  }
}