> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Try a worker on one message

> Runs one turn of the worker, live or under `changes` (the settings PATCH takes) or a saved `version_id`, and returns the reply it would send, whether it would wait for a person, and (`loop_in`) what it would hand a person on the account's team beside the reply. Nothing is sent or saved, and nothing outside Statisfy is called; the tools that only read run for real, as in the app's playground. A turn takes ten seconds to a minute. `untested` names the parts of `changes` one turn never reads. To make a change live, send it to PATCH /v1/digital_workers/{worker_id} with `if_unchanged_since`.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/digital_workers/{worker_id}/preview
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/digital_workers/{worker_id}/preview:
    post:
      tags:
        - digital_workers
      summary: Try a worker on one message
      description: >-
        Runs one turn of the worker, live or under `changes` (the settings PATCH
        takes) or a saved `version_id`, and returns the reply it would send,
        whether it would wait for a person, and (`loop_in`) what it would hand a
        person on the account's team beside the reply. Nothing is sent or saved,
        and nothing outside Statisfy is called; the tools that only read run for
        real, as in the app's playground. A turn takes ten seconds to a minute.
        `untested` names the parts of `changes` one turn never reads. To make a
        change live, send it to PATCH /v1/digital_workers/{worker_id} with
        `if_unchanged_since`.
      operationId: digital_workers_preview
      parameters:
        - description: The worker's id, from GET /v1/digital_workers
          in: path
          name: worker_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                account_id:
                  anyOf:
                    - maxLength: 255
                      minLength: 1
                      type: string
                    - type: 'null'
                  default: null
                  description: >-
                    The account the asker is at, from GET
                    /v1/objects/account/records. Without it the turn has no
                    account to read
                  title: Account Id
                changes:
                  $ref: '#/components/schemas/WorkerChanges'
                  default: null
                  description: >-
                    Settings to try instead of the live ones, as PATCH
                    /v1/digital_workers/{worker_id} takes them, without
                    `status`. Nothing is saved
                  title: Changes
                context:
                  anyOf:
                    - additionalProperties: true
                      type: object
                    - type: 'null'
                  default: null
                  description: >-
                    Facts about the asker, as the in-app SDK token's `context`
                    claim carries them, e.g. {"user_type": "Corporate
                    non-administrator"}. A part a live token would drop is
                    refused with a 422
                  title: Context
                message:
                  description: What the customer wrote
                  maxLength: 10000
                  minLength: 1
                  title: Message
                  type: string
                sender_name:
                  anyOf:
                    - maxLength: 255
                      type: string
                    - type: 'null'
                  default: null
                  description: The asker's name
                  title: Sender Name
                version_id:
                  anyOf:
                    - maxLength: 64
                      type: string
                    - type: 'null'
                  default: null
                  description: >-
                    Try a saved version instead. The version's id, from GET
                    /v1/digital_workers/{worker_id}/versions
                  title: Version Id
              required:
                - message
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewReply'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    WorkerChanges:
      additionalProperties: false
      description: >-
        A change to try before it goes live: the settings PATCH takes, without
        ``status``.
      properties:
        accounts:
          $ref: '#/components/schemas/AccountsChange'
          default: null
          title: Accounts
        assignment:
          $ref: '#/components/schemas/AssignmentChange'
          default: null
          title: Assignment
        autonomy:
          $ref: '#/components/schemas/AutonomyChange'
          default: null
          title: Autonomy
        channels:
          $ref: '#/components/schemas/ChannelsChange'
          default: null
          title: Channels
        description:
          anyOf:
            - maxLength: 10000
              type: string
            - type: 'null'
          default: null
          description: 'Its job, in plain words: every conversation it has opens with this'
          title: Description
        knowledge_base_ids:
          default: null
          description: >-
            The knowledge bases it searches when it answers, by id from GET
            /v1/knowledge_bases: replaced whole, [] clears them
          items:
            type: string
          maxItems: 100
          title: Knowledge Base Ids
          type: array
        name:
          default: null
          maxLength: 255
          minLength: 1
          title: Name
          type: string
        persona:
          $ref: '#/components/schemas/PersonaChange'
          default: null
          title: Persona
        skill_keys:
          default: null
          description: >-
            The skills it can use, by key from GET /v1/skills: replaced whole,
            [] clears them. A skill added must be one that list holds, and must
            not run in a sub-agent, which a worker never starts
          items:
            maxLength: 255
            minLength: 1
            type: string
          maxItems: 50
          title: Skill Keys
          type: array
      title: WorkerChanges
      type: object
    PreviewReply:
      properties:
        held:
          description: Whether it would wait for a person before it goes out
          title: Held
          type: boolean
        held_reason:
          anyOf:
            - type: string
            - type: 'null'
          description: Why it would wait, when it would
          title: Held Reason
        loop_in:
          anyOf:
            - $ref: '#/components/schemas/PreviewLoopIn'
            - type: 'null'
          description: >-
            The part of the message only a person can do, handed to the
            account's team beside the reply (which still answers the rest); null
            when nothing is left for a person. A reply that says a colleague
            will follow up has someone behind it only when this is set or the
            reply is held
        reply:
          description: The message the worker would send
          title: Reply
          type: string
        untested:
          description: >-
            The parts of `changes` one turn never reads (channels, autonomy,
            accounts, assignment): they take effect only once the change is live
          items:
            type: string
          title: Untested
          type: array
      required:
        - reply
        - held
        - held_reason
        - loop_in
        - untested
      title: PreviewReply
      type: object
    AccountsChange:
      additionalProperties: false
      properties:
        segment:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            The accounts it covers: an account segment, the JSON the app's
            account filter builder saves (`entity` 4, the account, and its
            `conditions`). Null covers none. GET
            /v1/digital_workers/{worker_id}/accounts lists what it selects
          title: Segment
      required:
        - segment
      title: AccountsChange
      type: object
    AssignmentChange:
      additionalProperties: false
      properties:
        owner_field:
          anyOf:
            - maxLength: 255
              minLength: 1
              type: string
            - type: 'null'
          default: null
          description: An account owner field's key; null clears it
          title: Owner Field
        people:
          default: null
          description: Teammates' person ids, replaced whole
          items:
            maxLength: 255
            minLength: 1
            type: string
          maxItems: 100
          title: People
          type: array
        strategy:
          default: null
          enum:
            - smart
            - round_robin
            - unassigned
          title: Strategy
          type: string
        to:
          default: null
          enum:
            - account_owner
            - people
          title: To
          type: string
        when_teammate_answers:
          default: null
          enum:
            - keep_owner
            - take_if_unowned
            - take
          title: When Teammate Answers
          type: string
      title: AssignmentChange
      type: object
    AutonomyChange:
      additionalProperties: false
      properties:
        channels:
          additionalProperties:
            anyOf:
              - enum:
                  - auto
                  - review
                type: string
              - type: 'null'
          default: null
          description: >-
            Each channel named follows this mode instead of `default`; null
            makes it follow `default` again. Channels left out are kept
          propertyNames:
            enum:
              - portal
              - in_app_sdk
              - email
              - slack
              - teams
          title: Channels
          type: object
        default:
          default: null
          description: >-
            auto sends on its own and holds a reply for a person when it judges
            one should look; review holds every reply for a person
          enum:
            - auto
            - review
          title: Default
          type: string
      title: AutonomyChange
      type: object
    ChannelsChange:
      additionalProperties: false
      properties:
        email:
          $ref: '#/components/schemas/EmailChannelChange'
          default: null
          title: Email
        in_app_sdk:
          $ref: '#/components/schemas/ChatChannelChange'
          default: null
          title: In App Sdk
        portal:
          $ref: '#/components/schemas/ChatChannelChange'
          default: null
          title: Portal
        slack:
          $ref: '#/components/schemas/SlackChannelChange'
          default: null
          title: Slack
        teams:
          $ref: '#/components/schemas/TeamsChannelChange'
          default: null
          title: Teams
      title: ChannelsChange
      type: object
    PersonaChange:
      additionalProperties: false
      properties:
        ai_disclosure:
          default: null
          enum:
            - transparent
            - branded
            - hybrid
          title: Ai Disclosure
          type: string
        greeting:
          anyOf:
            - maxLength: 10000
              type: string
            - type: 'null'
          default: null
          description: null clears it
          title: Greeting
        guardrails:
          anyOf:
            - maxLength: 10000
              type: string
            - type: 'null'
          default: null
          description: null clears it
          title: Guardrails
        voice:
          anyOf:
            - maxLength: 10000
              type: string
            - type: 'null'
          default: null
          description: null clears it
          title: Voice
      title: PersonaChange
      type: object
    PreviewLoopIn:
      properties:
        draft:
          description: >-
            The follow-up the worker drafted for them to finish and send; empty
            when none
          title: Draft
          type: string
        flag:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The guardrail's note on that draft, when it flagged it; the reply
            still goes out
          title: Flag
        note:
          description: What a person on the account's team is asked to do
          title: Note
          type: string
      required:
        - note
        - draft
        - flag
      title: PreviewLoopIn
      type: object
    EmailChannelChange:
      additionalProperties: false
      properties:
        acknowledge:
          default: null
          title: Acknowledge
          type: boolean
        acknowledgement:
          anyOf:
            - maxLength: 10000
              type: string
            - type: 'null'
          default: null
          description: What it tells the customer when a reply waits for a person
          title: Acknowledgement
        addresses:
          default: null
          description: Replaced whole
          items:
            maxLength: 320
            minLength: 3
            type: string
          maxItems: 20
          title: Addresses
          type: array
        company_address:
          anyOf:
            - maxLength: 320
              minLength: 3
              type: string
            - type: 'null'
          default: null
          description: null clears it
          title: Company Address
        enabled:
          default: null
          title: Enabled
          type: boolean
        forwarding:
          default: null
          title: Forwarding
          type: boolean
        shared_mailboxes:
          default: null
          description: Replaced whole
          items:
            maxLength: 320
            minLength: 3
            type: string
          maxItems: 20
          title: Shared Mailboxes
          type: array
        take_in_unknown_senders:
          default: null
          description: >-
            Whether mail to it from a sender it can't place (no account, or an
            account no worker covers) shows on the board for a person to answer;
            it never answers that mail itself. Unset, it is on for a support
            worker and off for any other
          title: Take In Unknown Senders
          type: boolean
        watch_mailboxes:
          default: null
          title: Watch Mailboxes
          type: boolean
      title: EmailChannelChange
      type: object
    ChatChannelChange:
      additionalProperties: false
      properties:
        acknowledgement:
          anyOf:
            - maxLength: 10000
              type: string
            - type: 'null'
          default: null
          description: What it tells the customer when a reply waits for a person
          title: Acknowledgement
        enabled:
          default: null
          title: Enabled
          type: boolean
      title: ChatChannelChange
      type: object
    SlackChannelChange:
      additionalProperties: false
      properties:
        acknowledge:
          default: null
          title: Acknowledge
          type: boolean
        acknowledgement:
          anyOf:
            - maxLength: 10000
              type: string
            - type: 'null'
          default: null
          description: What it tells the customer when a reply waits for a person
          title: Acknowledgement
        enabled:
          default: null
          title: Enabled
          type: boolean
        grouping:
          default: null
          enum:
            - thread
            - topic
          title: Grouping
          type: string
      title: SlackChannelChange
      type: object
    TeamsChannelChange:
      additionalProperties: false
      properties:
        acknowledge:
          default: null
          title: Acknowledge
          type: boolean
        acknowledgement:
          anyOf:
            - maxLength: 10000
              type: string
            - type: 'null'
          default: null
          description: What it tells the customer when a reply waits for a person
          title: Acknowledgement
        enabled:
          default: null
          title: Enabled
          type: boolean
      title: TeamsChannelChange
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.