> ## 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.

# Change, activate, stop or archive a digital worker

> Changes what you send of a worker's settings; each part keeps what it leaves out. `status` activates it (active), stops it (draft) or archives it. `knowledge_base_ids` sets the knowledge bases it searches, and `skill_keys` the skills it can use, each the whole list. Activating a worker, or changing an active one, needs digital_workers:activate too; stopping or archiving it doesn't. An active worker needs accounts, an assignment that reaches a person, and an acknowledgement for each enabled channel that sends one: a 422 lists what's missing. If the worker changes while yours is being checked, or another activation in your workspace keeps it waiting too long, a 409 asks you to read it again and send the change again.



## OpenAPI

````yaml /api/statisfy-api.openapi.json patch /v1/digital_workers/{worker_id}
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}:
    patch:
      tags:
        - digital_workers
      summary: Change, activate, stop or archive a digital worker
      description: >-
        Changes what you send of a worker's settings; each part keeps what it
        leaves out. `status` activates it (active), stops it (draft) or archives
        it. `knowledge_base_ids` sets the knowledge bases it searches, and
        `skill_keys` the skills it can use, each the whole list. Activating a
        worker, or changing an active one, needs digital_workers:activate too;
        stopping or archiving it doesn't. An active worker needs accounts, an
        assignment that reaches a person, and an acknowledgement for each
        enabled channel that sends one: a 422 lists what's missing. If the
        worker changes while yours is being checked, or another activation in
        your workspace keeps it waiting too long, a 409 asks you to read it
        again and send the change again.
      operationId: digital_workers_update
      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:
                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
                if_unchanged_since:
                  default: null
                  description: >-
                    The worker's `updated_at` as you read it. If the worker was
                    saved after that, a 409 and nothing is written: read it
                    again and try your change on it again
                  format: date-time
                  title: If Unchanged Since
                  type: string
                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
                status:
                  default: null
                  description: >-
                    draft, active or archived. Only an active worker answers or
                    writes to customers; a draft or archived one answers nobody
                  enum:
                    - draft
                    - active
                    - archived
                  title: Status
                  type: string
                version_label:
                  anyOf:
                    - maxLength: 200
                      type: string
                    - type: 'null'
                  default: null
                  description: >-
                    A label for the version this save adds, shown in the app's
                    Versions tab. Blank is none
                  title: Version Label
              type: object
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DigitalWorker'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    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
    DigitalWorker:
      properties:
        accounts:
          $ref: '#/components/schemas/Accounts'
        assignment:
          $ref: '#/components/schemas/Assignment'
        autonomy:
          $ref: '#/components/schemas/Autonomy'
          description: Whether its replies wait for a person
        avatar_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Avatar Url
        built_in:
          description: Whether it is the workspace's own worker, which Statisfy set up
          title: Built In
          type: boolean
        channels:
          $ref: '#/components/schemas/Channels'
          description: Where it answers customers
        created_at:
          description: ISO 8601 UTC
          title: Created At
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Its job, in plain words: every conversation it has opens with this'
          title: Description
        id:
          title: Id
          type: string
        kind:
          description: >-
            customer_success or support: a support worker answers customers'
            questions; any other is customer_success
          enum:
            - customer_success
            - support
          title: Kind
          type: string
        knowledge_bases:
          description: >-
            The knowledge bases it searches when it answers, in the order they
            were set
          items:
            $ref: '#/components/schemas/KnowledgeBaseRef'
          title: Knowledge Bases
          type: array
        name:
          title: Name
          type: string
        outreach_enabled:
          description: >-
            Whether it does its proactive tasks (GET
            /v1/digital_workers/{worker_id}/tasks): they run while this is on
            and the worker isn't archived. It is switched in the app
          title: Outreach Enabled
          type: boolean
        persona:
          $ref: '#/components/schemas/Persona'
        skills:
          description: The skills it can use when it answers, in the order they were set
          items:
            $ref: '#/components/schemas/WorkerSkill'
          title: Skills
          type: array
        status:
          description: >-
            draft, active or archived. Only an active worker answers or writes
            to customers; a draft or archived one answers nobody
          enum:
            - draft
            - active
            - archived
          title: Status
          type: string
        updated_at:
          description: ISO 8601 UTC
          title: Updated At
          type: string
      required:
        - id
        - name
        - description
        - kind
        - status
        - built_in
        - avatar_url
        - persona
        - channels
        - autonomy
        - accounts
        - assignment
        - knowledge_bases
        - skills
        - outreach_enabled
        - created_at
        - updated_at
      title: DigitalWorker
      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
    Accounts:
      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: Accounts
      type: object
    Assignment:
      properties:
        owner_field:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            An account field naming the account's owner, such as its CSM, from
            GET /v1/fields?object=account
          title: Owner Field
        people:
          description: Teammates' person ids
          items:
            type: string
          title: People
          type: array
        strategy:
          description: >-
            How it picks among `people`: smart (the one with the fewest open
            conversations), round_robin (in turn) or unassigned (left for anyone
            to take)
          enum:
            - smart
            - round_robin
            - unassigned
          title: Strategy
          type: string
        to:
          description: >-
            Who a conversation it hands to a person is assigned to:
            account_owner (the person in the account's `owner_field`) or people
            (one of `people`, picked by `strategy`)
          enum:
            - account_owner
            - people
          title: To
          type: string
        when_teammate_answers:
          description: >-
            Who owns a conversation once a teammate answers in it: keep_owner,
            take_if_unowned (the teammate, when nobody owns it) or take (the
            teammate)
          enum:
            - keep_owner
            - take_if_unowned
            - take
          title: When Teammate Answers
          type: string
      required:
        - to
        - owner_field
        - people
        - strategy
        - when_teammate_answers
      title: Assignment
      type: object
    Autonomy:
      properties:
        channels:
          additionalProperties:
            enum:
              - auto
              - review
            type: string
          description: Channels that don't follow `default`, and what they do instead
          propertyNames:
            enum:
              - portal
              - in_app_sdk
              - email
              - slack
              - teams
          title: Channels
          type: object
        default:
          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
      required:
        - default
        - channels
      title: Autonomy
      type: object
    Channels:
      properties:
        email:
          $ref: '#/components/schemas/EmailChannel'
        in_app_sdk:
          $ref: '#/components/schemas/ChatChannel'
          description: The chat widget in your own product
        portal:
          $ref: '#/components/schemas/ChatChannel'
          description: Your customer portal's chat
        slack:
          $ref: '#/components/schemas/SlackChannel'
          description: Your shared Slack channels with customers
        teams:
          $ref: '#/components/schemas/TeamsChannel'
          description: Your Microsoft Teams chats with customers
      required:
        - portal
        - in_app_sdk
        - email
        - slack
        - teams
      title: Channels
      type: object
    KnowledgeBaseRef:
      properties:
        id:
          description: >-
            The knowledge base's id, from GET /v1/knowledge_bases. A worker
            saved in the app may also hold one an Agent Studio agent keeps for
            its own files, which that list leaves out; it can keep it, but not
            add it again once removed
          title: Id
          type: string
        name:
          title: Name
          type: string
      required:
        - id
        - name
      title: KnowledgeBaseRef
      type: object
    Persona:
      properties:
        ai_disclosure:
          anyOf:
            - enum:
                - transparent
                - branded
                - hybrid
              type: string
            - type: 'null'
          description: >-
            How it says it is an AI: transparent (the first time it writes to
            someone), branded (it uses its name, and says so only when asked) or
            hybrid (when it matters, such as before promising a follow-up)
          title: Ai Disclosure
        greeting:
          anyOf:
            - type: string
            - type: 'null'
          description: Its first message in the portal and the in-app chat
          title: Greeting
        guardrails:
          anyOf:
            - type: string
            - type: 'null'
          description: Rules it always follows, ahead of everything else it is told
          title: Guardrails
        voice:
          anyOf:
            - type: string
            - type: 'null'
          description: 'How it writes: its tone, and how it addresses people'
          title: Voice
      required:
        - voice
        - greeting
        - ai_disclosure
        - guardrails
      title: Persona
      type: object
    WorkerSkill:
      properties:
        enabled:
          description: >-
            Whether it is on in your workspace (`enabled` on GET /v1/skills):
            the worker skips one that is off, archived or gone
          title: Enabled
          type: boolean
        key:
          description: The skill's key, from GET /v1/skills
          title: Key
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Null when the key names no skill your workspace has: the worker
            skips it
          title: Name
      required:
        - key
        - name
        - enabled
      title: WorkerSkill
      type: object
    EmailChannel:
      properties:
        acknowledge:
          description: Whether it acknowledges an email whose reply waits for a person
          title: Acknowledge
          type: boolean
        acknowledgement:
          anyOf:
            - type: string
            - type: 'null'
          description: What it tells the customer when a reply waits for a person
          title: Acknowledgement
        addresses:
          description: >-
            The mailboxes it reads and sends from: each a Google Workspace or
            Microsoft 365 mailbox connected to Statisfy with read and send,
            which no other active worker claims
          items:
            type: string
          title: Addresses
          type: array
        company_address:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The company mailbox that forwards to it. Its replies are sent as it,
            and copy it
          title: Company Address
        enabled:
          title: Enabled
          type: boolean
        forwarding:
          description: Whether it answers the mail your company mailbox forwards to it
          title: Forwarding
          type: boolean
        shared_mailboxes:
          description: >-
            Microsoft 365 shared mailboxes it reads through a teammate's
            delegated access
          items:
            type: string
          title: Shared Mailboxes
          type: array
        take_in_unknown_senders:
          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:
          description: Whether it reads the mail that reaches `addresses`
          title: Watch Mailboxes
          type: boolean
      required:
        - enabled
        - addresses
        - shared_mailboxes
        - watch_mailboxes
        - forwarding
        - company_address
        - take_in_unknown_senders
        - acknowledge
        - acknowledgement
      title: EmailChannel
      type: object
    ChatChannel:
      properties:
        acknowledgement:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            What it tells the customer when a reply waits for a person; an
            enabled channel always sends it
          title: Acknowledgement
        enabled:
          title: Enabled
          type: boolean
      required:
        - enabled
        - acknowledgement
      title: ChatChannel
      type: object
    SlackChannel:
      properties:
        acknowledge:
          description: Whether it acknowledges a message whose reply waits for a person
          title: Acknowledge
          type: boolean
        acknowledgement:
          anyOf:
            - type: string
            - type: 'null'
          description: What it tells the customer when a reply waits for a person
          title: Acknowledgement
        enabled:
          title: Enabled
          type: boolean
        grouping:
          description: >-
            How its Slack messages become conversations: one per thread, or
            related messages grouped by topic
          enum:
            - thread
            - topic
          title: Grouping
          type: string
      required:
        - enabled
        - grouping
        - acknowledge
        - acknowledgement
      title: SlackChannel
      type: object
    TeamsChannel:
      properties:
        acknowledge:
          description: Whether it acknowledges a message whose reply waits for a person
          title: Acknowledge
          type: boolean
        acknowledgement:
          anyOf:
            - type: string
            - type: 'null'
          description: What it tells the customer when a reply waits for a person
          title: Acknowledgement
        enabled:
          title: Enabled
          type: boolean
      required:
        - enabled
        - acknowledge
        - acknowledgement
      title: TeamsChannel
      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.