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

# Start a run

> Queues a run of one set. Optionally send a `config`, `changes` or a `version_id` to run with instead of the worker's saved settings — it is recorded against the run and never written to the worker, so tuning cannot change live behaviour. Each case is a full agent session, so a run takes minutes: poll GET /v1/evaluations/runs/{run_id} for its status. Nothing the worker does in a run is sent, saved or queued.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/evaluations/runs
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/evaluations/runs:
    post:
      tags:
        - evaluations
      summary: Start a run
      description: >-
        Queues a run of one set. Optionally send a `config`, `changes` or a
        `version_id` to run with instead of the worker's saved settings — it is
        recorded against the run and never written to the worker, so tuning
        cannot change live behaviour. Each case is a full agent session, so a
        run takes minutes: poll GET /v1/evaluations/runs/{run_id} for its
        status. Nothing the worker does in a run is sent, saved or queued.
      operationId: evaluations_start_run
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                case_set_id:
                  description: The case set, from POST /v1/evaluations/case_sets.
                  title: Case Set Id
                  type: string
                changes:
                  anyOf:
                    - $ref: '#/components/schemas/WorkerChanges'
                    - type: 'null'
                  default: null
                  description: >-
                    Run with these settings instead of the worker's saved ones,
                    as PATCH /v1/digital_workers/{worker_id} takes them (without
                    `status`). Like `config`, never written to the worker.
                config:
                  anyOf:
                    - additionalProperties: true
                      type: object
                    - type: 'null'
                  default: null
                  description: >-
                    Run with this configuration INSTEAD of the worker's saved
                    one. It is recorded against the run and never written to the
                    worker, so an experiment cannot change live behaviour. Omit
                    it to run the worker as it stands.
                  title: Config
                label:
                  anyOf:
                    - maxLength: 200
                      type: string
                    - type: 'null'
                  default: null
                  description: Shown against the run, e.g. 'warmer opening'.
                  title: Label
                version_id:
                  anyOf:
                    - maxLength: 64
                      type: string
                    - type: 'null'
                  default: null
                  description: >-
                    Run one of the worker's saved versions, by id from GET
                    /v1/digital_workers/{worker_id}/versions.
                  title: Version Id
              required:
                - case_set_id
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
          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
    Run:
      properties:
        case_set_id:
          title: Case Set Id
          type: string
        config_snapshot:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Config Snapshot
        error:
          anyOf:
            - type: string
            - type: 'null'
          description: Why the run as a whole failed. Per-case failures sit on the result.
          title: Error
        finished_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Finished At
        id:
          title: Id
          type: string
        judged_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Judged By
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
        started_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Started At
        started_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Started By
        status:
          description: '`queued`, `running`, `done` or `failed`.'
          title: Status
          type: string
        totals:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Counts over the run's results: cases, how many are judged, how many
            passed, how many could not run at all, and the mean score. They
            follow the verdicts, so a run that nobody has scored yet reports
            nothing judged.
          title: Totals
        untested:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: >-
            On the response that starts a run with `changes`: the parts of them
            a run never reads (channels, autonomy, accounts, assignment). Not
            stored: null on a later read.
          title: Untested
        worker_id:
          title: Worker Id
          type: string
      required:
        - id
        - case_set_id
        - worker_id
        - status
      title: Run
      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
    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.