Operator Documentation

Updated 14 March 2026 API Version: v2.1

Welcome. These docs cover the Operator rules engine, workflow automation, and AI contact centre. If you're setting up for the first time, start with the Quickstart.

Overview

The Operator platform is built around three core primitives: Rules, Workflows, and Events.

Rules are conditional logic blocks that evaluate incoming data against defined thresholds.
Workflows are ordered sequences of stages that an entity progresses through as rules are satisfied.
Events are emitted whenever a rule is evaluated, a stage transitions, or a payment executes — available via webhook or the event log API.

All platform behaviour is deterministic: given the same inputs, the engine will always produce the same output. This is intentional — Operator is designed to be auditable, predictable, and scriptable.

Quickstart

The fastest path to a running workflow is three steps: create a Rule, attach it to a Workflow Stage, and submit an entity for evaluation.

1. Create a Rule

                    JSON
// POST /v2/rules
{
  "name": "minimum_experience_check",
  "description": "Requires 3+ years of verified experience",
  "condition": {
    "field": "applicant.verified_years",
    "operator": "gte",
    "value": 3
  },
  "on_pass": "advance_stage",
  "on_fail": "reject_with_reason"
}
                

2. Link to a Workflow Stage

                    JSON
// POST /v2/workflows/{workflow_id}/stages
{
  "stage_name": "Initial Qualification",
  "rules": ["minimum_experience_check", "id_verification_passed"],
  "mode": "all_required",
  "on_complete": {
    "action": "emit_quote",
    "quote_template": "standard_contractor_v2"
  }
}
                

3. Submit an entity for evaluation

                    cURL
curl -X POST https://api.onoperator.com/v2/evaluate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_01J2...",
    "entity": {
      "applicant": {
        "verified_years": 5,
        "id_verified": true
      }
    }
  }'
                

Authentication

All Operator API requests are authenticated via Bearer tokens. Generate an API key from your workspace settings under Settings → API Keys.

Keep API keys secret. Do not expose them in client-side code or public repositories. Use environment variables or a secrets manager.

Defining Rules

Rules define boolean conditions evaluated against entity data. Each rule specifies a field, an operator, and a value.

Supported Operators

Operator	Description	Types
`eq`	Equal to	string, number, boolean
`neq`	Not equal to	string, number, boolean
`gte`	Greater than or equal	number, date
`lte`	Less than or equal	number, date
`in`	Value exists in array	string, number
`contains`	String contains substring	string
`regex`	Matches regex pattern	string

Thresholds

Thresholds are weighted or absolute score gates used to aggregate multiple rule outputs into a single qualification decision. They are useful for risk scoring, competency assessment, or weighted pricing calculations.

                    JSON
{
  "threshold": {
    "type": "weighted_score",
    "minimum_score": 75,
    "rules": [
      { "rule_id": "experience_check", "weight": 40 },
      { "rule_id": "qualification_check", "weight": 35 },
      { "rule_id": "reference_check", "weight": 25 }
    ]
  }
}
                

Logic Trees

For advanced routing, group rules into nested branches. Logic trees let you model flows such as “all compliance checks must pass, then at least one commercial qualifier must be true” without custom code.

                    JSON
{
  "tree": {
    "operator": "and",
    "children": [
      { "rule_id": "kyc_passed" },
      {
        "operator": "or",
        "children": [
          { "rule_id": "manual_reference_uploaded" },
          { "rule_id": "verified_trading_history" }
        ]
      }
    ]
  }
}
                

Actions & Triggers

Each rule or stage outcome can trigger one or more actions. Common examples include advancing an entity, generating a quote, notifying an operator, requesting payment, or opening the next portal view.

advance_stage moves the entity into the next configured workflow step.
emit_quote returns a deterministic quote payload from approved inputs.
notify_operator creates an internal alert with full evaluation context.
trigger_payment starts a deposit or milestone collection step.

Workflow Stages

Workflows are explicit sequences of stages. Every stage has entry requirements, evaluation logic, and completion actions, which makes audits simple because you can reconstruct exactly why an entity advanced or stopped.

Stage Gating

Use gating when progression depends on a hard prerequisite such as verified identity, signed documents, or completed deposit payment. Gates are binary by design: if a requirement is missing, the stage remains locked.

Payment Execution

Payments are tied to workflow state rather than free-form invoices. That means deposits, milestone releases, and settlement events can all be triggered from the same deterministic execution log.

SDKs & Libraries

Official Operator SDKs are available for the following platforms:

Node.js — npm install @operator/sdk
Python — pip install operator-sdk
Go — go get github.com/onoperator/go-sdk

Webhooks

Operator emits events to your configured webhook endpoint for real-time notifications. Subscribe to specific event types to reduce payload volume.

Event Types

rule.passed — A rule evaluation returned true.
rule.failed — A rule evaluation returned false.
workflow.stage_advanced — An entity advanced to the next stage.
workflow.completed — Workflow reached terminal state.
payment.initiated — Staged payment was triggered.
payment.confirmed — Payment settled successfully.

Changelog

14 March 2026: Added weighted thresholds examples and clarified webhook signing guidance.
28 February 2026: Documented staged payment execution endpoints and workflow gating behavior.
11 February 2026: Published SDK install commands for Node, Python, and Go.