usewrit-app Personas API

openapi: 3.2.0
info:
  title: Writ Agent Personas API
  version: 0.1.0
  license:
    name: MIT
    identifier: MIT
  description: 'Loopback HTTP API of the Writ local agent (`writ-agentd`), the daemon embedded in the

    Writ desktop app and the self-host build. This document is generated against the Rust

    daemon source (`writ-agent/src/local/`), which is the wire truth.


    ## Transport


    - Plain HTTP on `127.0.0.1:8131` (default; `WRIT_PORT` env overrides).

    - Optional HTTPS twin on `127.0.0.1:8132`, served with a certificate minted by a

    per-install, name-constrained local CA (`~/.writ/tls/ca.pem`). Clients must trust that

    CA file (or pin it) to use the TLS port; the payloads are identical on both ports.

    - The daemon enforces a DNS-rebind guard: `Host`/`Origin` must be loopback. Talk to

    `127.0.0.1`, not `localhost`.


    ## Errors


    Domain errors are JSON `{"error": "", "code": ""}` (see the

    `Error` schema). Codes include `bad_request`, `unauthorized`, `forbidden`, `not_found`,

    `vault_locked` (HTTP 423), `too_many_requests`, `device_capacity` (HTTP 409),

    `captcha_required` (HTTP 402), `internal`.


    **Caveat:** some 4xx bodies are `text/plain`, not JSON — axum framework rejections

    (e.g. a JSON body that fails to deserialize returns

    `Failed to deserialize the JSON body into the target type: missing field ''url''` as

    plain text with a 4xx status). Clients must tolerate non-JSON error bodies.


    ## List envelopes


    The wire is deliberately documented as-is (SDKs normalize; this spec does not):


    - `{"data": [...], "count": n}` — workflows, personas, persona runs, secrets, files, keys

    - `{"data": [...], "count": n, "total": n}` — runs

    - **bare JSON array** — monitors, monitor selectors, extractors, automations,

    `/v1/changes/recent`

    - bespoke objects — `/v1/monitors/{id}/changes`, `/v1/data`, the workflow-data table'
servers:
- url: http://127.0.0.1:8131
  description: Plain-HTTP loopback listener (default port; WRIT_PORT overrides).
- url: https://127.0.0.1:8132
  description: HTTPS twin of the same API, terminated with a certificate from the per-install local CA at ~/.writ/tls/ca.pem. Trust that CA (or pin it) in your HTTP client.
security:
- bearerAuth: []
tags:
- name: Personas
  description: Login identities (credentials, TOTP, fingerprint, proxy) — secrets sealed daemon-side.
paths:
  /v1/personas:
    get:
      operationId: listPersonas
      tags:
      - Personas
      summary: List personas
      description: Newest-first persona list in the `{data, count}` envelope. Secrets collapse to `has_*` booleans and `linked_secrets` NAMES; no encrypted column or plaintext value ever appears. `?domain=` keeps personas with no domain, the same domain, or a parent domain of the requested host (suffix semantics).
      parameters:
      - name: limit
        in: query
        description: Page size (clamped to 1..=500; default 100).
        schema:
          type: integer
          format: int64
          default: 100
      - name: domain
        in: query
        description: Suggest-by-domain filter (suffix match, case-insensitive).
        schema:
          type: string
      responses:
        '200':
          description: Persona page in the `{data, count}` envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonaList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPersona
      tags:
      - Personas
      summary: Create a persona
      description: 'Creates a persona from a plaintext payload; the handler seals `password`, `extra_login_fields`, `totp_seed` and `proxy_*` into row-bound encrypted blobs. Requires a unique non-empty `name`. Setting a proxy requires `proxy_lawful_use_ack: true`. Returns 423 while the vault app-lock is locked.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonaWrite'
      responses:
        '200':
          description: The created persona (shaped; secrets reduced to has_* flags).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '423':
          $ref: '#/components/responses/VaultLocked'
  /v1/personas/{id}:
    parameters:
    - $ref: '#/components/parameters/PersonaId'
    get:
      operationId: getPersona
      tags:
      - Personas
      summary: Get one persona
      description: One shaped persona or 404.
      responses:
        '200':
          description: The persona.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updatePersona
      tags:
      - Personas
      summary: Update a persona
      description: 'Partial update with cloud replace semantics on secrets: sending `password` / `extra_login_fields` replaces the whole stored credential set; an empty `totp_seed` or `proxy_server` clears that blob. Returns 423 while the vault app-lock is locked.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonaWrite'
      responses:
        '200':
          description: The refreshed persona.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/VaultLocked'
    delete:
      operationId: deletePersona
      tags:
      - Personas
      summary: Delete a persona
      description: Hard-delete.
      responses:
        '200':
          description: Deletion acknowledgement.
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - deleted
                properties:
                  id:
                    type: integer
                    format: int64
                  deleted:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/personas/{id}/runs:
    get:
      operationId: listPersonaRuns
      tags:
      - Personas
      summary: Recent runs that acted as this persona
      description: Runs of the workflows whose `default_persona_id` is this persona, newest first, in the `{data, count}` envelope.
      parameters:
      - $ref: '#/components/parameters/PersonaId'
      - name: limit
        in: query
        description: Max entries (default 20).
        schema:
          type: integer
          format: int64
          default: 20
      responses:
        '200':
          description: Persona run page in the `{data, count}` envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonaRunList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/personas/validate-totp:
    post:
      operationId: validateTotp
      tags:
      - Personas
      summary: Validate a TOTP seed
      description: Confirms a pasted seed is well-formed base32 and (optionally) that it reproduces a code the user just saw (one time-step of clock skew tolerated). The seed and code are never stored or logged. `matches_code` is `null` when no code was supplied or the seed is invalid.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateTotpRequest'
      responses:
        '200':
          description: Validation verdict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateTotpResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/personas/{id}/test-2fa:
    post:
      operationId: testPersona2fa
      tags:
      - Personas
      summary: Smoke-test the persona's 2FA
      description: Confirms the persona can mint a 2FA value — the code itself is NEVER returned. TOTP mints fully on-device; email/SMS OTP reading is a cloud capability and answers with a 400 explaining the cloud gate. Returns 423 while the vault app-lock is locked.
      parameters:
      - $ref: '#/components/parameters/PersonaId'
      responses:
        '200':
          description: The 2FA test verdict (no code included).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Test2faResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/VaultLocked'
components:
  schemas:
    PersonaWrite:
      type: object
      description: 'Shared create/update payload. Plaintext secrets (`password`, `extra_login_fields`, `totp_seed`, `proxy_*`) are sealed by the handler and never echoed. Several fields distinguish "absent = untouched" from "explicit null = clear" (`description`, `target_domain`, `login_username`, `fingerprint`). Secrets follow cloud replace semantics: sending `password`/`extra_login_fields` replaces the whole credential set (empty ⇒ cleared); an empty-string `totp_seed`/`proxy_server` clears that blob. Unknown (cloud-only) fields are ignored.'
      properties:
        name:
          type:
          - string
          - 'null'
          description: Required (non-empty) on create; renames on update (must stay unique).
        description:
          type:
          - string
          - 'null'
          description: Explicit null clears.
        target_domain:
          type:
          - string
          - 'null'
          description: Explicit null clears.
        login_username:
          type:
          - string
          - 'null'
          description: Literal username or `{{vault:key.username}}` ref; explicit null clears.
        password:
          type:
          - string
          - 'null'
          description: Plaintext password or `{{vault:key.password}}` ref; empty clears the credential set.
        extra_login_fields:
          type:
          - object
          - 'null'
          description: 'Additional plaintext login fields `{name: value}`.'
          additionalProperties:
            type: string
        twofa_method:
          type:
          - string
          - 'null'
          enum:
          - none
          - totp
          - email_otp
          - sms
          - null
        totp_seed:
          type:
          - string
          - 'null'
          description: Plaintext base32 seed; empty string on update clears the stored seed.
        totp_digits:
          type:
          - integer
          - 'null'
          format: int64
        totp_period_seconds:
          type:
          - integer
          - 'null'
          format: int64
        totp_algorithm:
          type:
          - string
          - 'null'
        email_otp_mode:
          type:
          - string
          - 'null'
          enum:
          - oauth_mailbox
          - relay
          - null
        relay_address:
          type:
          - string
          - 'null'
        otp_extract_config:
          type:
          - object
          - 'null'
          description: Email-OTP extraction hints (object); null clears.
        fingerprint:
          type:
          - object
          - 'null'
          description: '`{user_agent, locale, timezone}` object to pin; explicit null unpins.'
        proxy_server:
          type:
          - string
          - 'null'
          description: BYO proxy server; non-empty requires `proxy_lawful_use_ack`; empty clears.
        proxy_username:
          type:
          - string
          - 'null'
        proxy_password:
          type:
          - string
          - 'null'
        proxy_lawful_use_ack:
          type:
          - boolean
          - 'null'
        is_active:
          type:
          - boolean
          - 'null'
    ValidateTotpRequest:
      type: object
      required:
      - totp_seed
      properties:
        totp_seed:
          type: string
          description: The pasted base32 seed (never stored or logged).
        code:
          type:
          - string
          - 'null'
          description: Optional code the user just saw, to cross-check the seed.
        algorithm:
          type:
          - string
          - 'null'
          description: Default SHA1.
        digits:
          type:
          - integer
          - 'null'
          description: Default 6 (clamped 6..=10).
        period:
          type:
          - integer
          - 'null'
          description: Default 30 seconds.
    ValidateTotpResult:
      type: object
      required:
      - valid_base32
      - matches_code
      properties:
        valid_base32:
          type: boolean
        matches_code:
          type:
          - boolean
          - 'null'
          description: Null when no code was supplied or the seed is invalid.
    Persona:
      type: object
      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.
      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
    Error:
      type: object
      description: 'The daemon''s domain error body. NOTE: some 4xx responses (axum framework rejections) are `text/plain` instead of this JSON shape. Certain codes attach extra fields (e.g. `device_capacity` adds `would_use_units_per_min` / `budget_units_per_min`; `captcha_required` adds `captcha_type` / `url`).'
      required:
      - error
      - code
      properties:
        error:
          type: string
          description: 'Human-readable message (e.g. `not found: workflow 999999`).'
        code:
          type: string
          description: 'Stable machine code: `bad_request`, `unauthorized`, `forbidden`, `not_found`, `vault_locked`, `too_many_requests`, `captcha_required`, `device_capacity`, `cloud_unreachable`, `db_error`, `io_error`, `json_error`, `internal`, …'
      additionalProperties: true
    PersonaList:
      type: object
      description: '`{data, count}` list envelope.'
      required:
      - data
      - count
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Persona'
        count:
          type: integer
    PersonaRun:
      type: object
      description: One recent run that acted as this persona (cloud `PersonaRun` wire shape).
      required:
      - task_id
      - workflow_id
      - workflow_name
      - status
      - success
      - started_at
      - completed_at
      - error
      properties:
        task_id:
          type: integer
          format: int64
          description: The run row id.
        workflow_id:
          type:
          - integer
          - 'null'
          format: int64
        workflow_name:
          type:
          - string
          - 'null'
        status:
          type: string
        success:
          type:
          - boolean
          - 'null'
        started_at:
          type:
          - string
          - 'null'
        completed_at:
          type:
          - string
          - 'null'
        error:
          type:
          - string
          - 'null'
          description: Truncated to 200 characters.
    Test2faResult:
      type: object
      description: '2FA smoke-test verdict. `method: "none"` carries a `message`; `method: "totp"` carries `kind: "totp"`. The minted code is NEVER returned. Email/SMS methods answer 400 (cloud-gated) instead of this shape.'
      required:
      - ok
      - method
      properties:
        ok:
          type: boolean
          const: true
        method:
          type: string
          enum:
          - none
          - totp
        message:
          type: string
          description: 'Present for `method: "none"`.'
        kind:
          type: string
          const: totp
          description: 'Present for `method: "totp"`.'
    PersonaRunList:
      type: object
      description: '`{data, count}` list envelope.'
      required:
      - data
      - count
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PersonaRun'
        count:
          type: integer
  responses:
    NotFound:
      description: The addressed resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    VaultLocked:
      description: The vault app-lock is engaged and locked (HTTP 423). Unlock via `POST /v1/vault/unlock`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing/invalid bearer token, or the Origin/Host guard rejected the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: 'Invalid input. Domain validation errors use the JSON Error shape; axum body-deserialize rejections are `text/plain` with a bare message (e.g. `Failed to deserialize the JSON body into the target type: missing field ''url''`).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        text/plain:
          schema:
            type: string
  parameters:
    PersonaId:
      name: id
      in: path
      required: true
      description: Persona row id.
      schema:
        type: integer
        format: int64
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "Every route (including `/v1/agent` and `/v1/health`) requires\n`Authorization: Bearer <token>`. Token families:\n\n- `wlt_…` — the runtime token from `runtime.json` (full access, used by the desktop\n  UI and SDK discovery).\n- `wlk_…` — a scoped API key minted via `POST /v1/keys` (CSV scopes `read|run|admin`;\n  `/v1/keys` itself requires the full-access token).\n- `wlo_…` — an OAuth 2.1 access token from the daemon's local authorization server\n  (`run` scope).\n\nTreat the token as an opaque string. The daemon additionally enforces a loopback\nOrigin/Host DNS-rebind guard.\n"