API Documentation

Agent Configuration (wauldo.toml)

wauldo.toml declares the agent's identity: which model to call, how strict verification should be, where the agent runs, and whether it remembers prior runs. It's the single file that controls behavior across all /v1/agents/:id/runs calls. AGENTS.md (optional) layers natural-language behavior instructions on top.

Minimal example

Two required sections, defaults applied for everything else.

[agent]
name = "support-bot"

[model]
provider = "openrouter"
name = "auto"

Full example (all sections)

[agent]
name = "support-bot"
description = "Handles customer support questions"
instructions = "./AGENTS.md"     # behavior file path
skills = "./skills/"             # skills directory
mcp = "./mcp.json"                # MCP server config

[model]
provider = "openrouter"           # openrouter | openai | anthropic | ollama
name = "auto"                    # "auto" for smart routing, or any provider model id
fallback = ["auto"]                # tried in order if primary fails
temperature = 0.2

[sandbox]
type = "none"                     # none | docker | daytona | modal | runloop

[verification]
mode = "balanced"                 # strict | balanced | permissive
min_trust_score = 0.6            # 0.0 – 1.0; reject below this

[deploy]
target = "local"                  # local | fly | render | selfhost
region = "cdg"

[memory]
enabled = true
namespace = "support"
auto_write = true

Field reference

Pass the file's contents as the wauldo_toml string field on POST /v1/agents. Validation runs server-side: missing required fields or out-of-range values return 400.

AGENTS.md (optional)

# Support Bot

You are a customer support agent for Acme Corp.

## Rules
- Answer questions based ONLY on the uploaded documents.
- If the answer is not in your sources, say "I don't have this information."
- Never invent facts or numbers.
- Be concise and professional.

Available Presets

A preset is a built-in multi-state workflow that shapes how the agent reasons before answering. Pass the preset name as the preset field on POST /v1/agents (set at agent creation) or as {"preset": "..."} on POST /v1/agents/:id/runs to override per-run. If omitted, runs default to general_task. wauldo.toml + AGENTS.md control identity, model, and tone — the multi-state workflow comes from the preset.

Invoke a preset via the API

curl -X POST https://api.wauldo.com/v1/agents/ag_abc123/runs \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "x-rapidapi-user: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Critique my Axum service auth layer",
    "preset": "rust_backend_architect",
    "verification_mode": "balanced"
  }'

# Returns: { "task_id": "t_xyz", "status": "queued" }
# Stream state-by-state via GET /v1/tasks/t_xyz/stream

Custom workflows

Beyond the six presets, you can send your own workflow inline via the custom_preset field on POST /v1/agents. Format matches the built-in presets: workflow.states (allowed_tools, parallel_group, required_outputs), transitions, system, guardrails. Server enforces hard limits — max 50 states, ≤256 KB JSON, no transition cycles, every state's allowed_tools must reference a tool currently registered.

Inline a custom workflow

curl -X POST https://api.wauldo.com/v1/agents \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "x-rapidapi-user: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-triage-agent",
    "wauldo_toml": "[agent]\nname=\"triage\"\n[model]\nprovider=\"openrouter\"\nname=\"auto\"",
    "custom_preset": {
      "version": "2.0",
      "metadata": { "name": "MyTriage", "strict_mode": false },
      "system": { "role": "Issue triage assistant" },
      "workflow": {
        "default_steps": ["Classify", "Answer"],
        "states": {
          "Classify": { "allowed_tools": ["wikipedia"] },
          "Answer":   { "allowed_tools": [] }
        },
        "transitions": [
          { "from_state": "Classify", "to_state": "Answer", "condition_trigger": "always" }
        ]
      },
      "output_formats": { "default": { "schema": { "schema_type": "object", "required": [], "properties": {} } } },
      "guardrails": { "forbidden_behaviors": ["leak credentials"] }
    }
  }'

# custom_preset takes precedence over the built-in `preset` field if both are set.

Need an even larger graph or stricter limits raised? contact@wauldo.com — quotas can be tuned per tenant.

Endpoints

All authenticated endpoints require Authorization: Bearer YOUR_KEY and x-rapidapi-user: YOUR_TENANT_ID. Poll GET /v1/tasks/:id or stream GET /v1/tasks/:id/stream to retrieve the run result.

Verification Modes

Every agent run goes through the verification pipeline. Control the strictness:

Verdict enum

Each completed task returns a verification.verdict. Pair it with verification.trust_score (0.0 – 1.0) and the optional verification.message for display.

Note on UNVERIFIED: when verification_source = "prompt_only", the returned confidence and hallucination_rate reflect self-consistency of the LLM output against the prompt — not ground-truth fact-checking. trust_score is forced to 0.0 in that case. Treat verdict + trust_score + message as authoritative.

Python SDK

import json, time, urllib.request

BASE = "https://api.wauldo.com"
HEADERS = {
    "Authorization": "Bearer YOUR_KEY",
    "x-rapidapi-user": "my-tenant",
    "Content-Type": "application/json",
}

# Create agent
agent = post("/v1/agents", {
    "name": "my-bot",
    "wauldo_toml": '[agent]\nname = "my-bot"\n\n[model]\nprovider = "openrouter"\nname = "auto"',
})

# Upload docs
post("/v1/upload", {"content": "Your document text...", "filename": "doc.txt"})

# Run agent
run = post(f"/v1/agents/{agent['id']}/runs", {"input": "What is the refund policy?"})

# Poll for result
while True:
    task = get(f"/v1/tasks/{run['task_id']}")
    if task["status"] == "completed":
        print(task["result"])                      # Verified answer
        print(task["verification"]["verdict"])     # SAFE
        print(task["verification"]["trust_score"])  # 1.0
        break
    time.sleep(3)

Streaming (SSE) — GET /v1/tasks/:id/stream

Instead of polling, subscribe to Server-Sent Events to receive each workflow state transition as it completes. Ideal for long-running multi-state agents (RustArchitect, SecurityAuditor, etc.) where you want to stream reasoning in the UI. Each data: line is a JSON-encoded StateTransition.

The stream closes when the task reaches a terminal status (completed / failed / cancelled). After closure, call GET /v1/tasks/:id once to fetch the full verification block and final result. Connection TTL is 30 minutes; reconnect if needed — already-emitted events are not replayed, so resubscribers only see subsequent transitions.

# Python — consume SSE with the stdlib
import json, urllib.request

req = urllib.request.Request(
    f"https://api.wauldo.com/v1/tasks/{task_id}/stream",
    headers={
        "Authorization": "Bearer YOUR_KEY",
        "x-rapidapi-user": "my-tenant",
        "Accept": "text/event-stream",
    },
)
with urllib.request.urlopen(req) as resp:
    for raw in resp:
        line = raw.decode().rstrip()
        if line.startswith("data:"):
            ev = json.loads(line[5:].strip())
            print(f"{ev['state_name']:<16} {ev['duration_ms']:>5}ms  {ev['completion_tokens']}tok")

// TypeScript — native EventSource (browser or bun/deno)
const headers = {
  "Authorization": "Bearer YOUR_KEY",
  "x-rapidapi-user": "my-tenant",
  "Accept": "text/event-stream",
};

const resp = await fetch(`https://api.wauldo.com/v1/tasks/${taskId}/stream`, { headers });
const reader = resp.body!.getReader();
const decoder = new TextDecoder();
let buf = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  for (const line of buf.split("\n")) {
    if (line.startsWith("data:")) {
      const ev = JSON.parse(line.slice(5).trim());
      console.log(ev.state_name, ev.duration_ms, ev.completion_tokens);
    }
  }
  buf = buf.slice(buf.lastIndexOf("\n") + 1);
}

Endpoints

# Mint a new revision (becomes active by default)
curl -X POST https://api.wauldo.com/v1/agents/AGENT_ID/revisions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "x-rapidapi-user: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_preset": { "version": "2.0", "workflow": { "states": [...] } },
    "message": "tighten triage prompt",
    "set_active": true
  }'

# Returns: { "rev": 4, "sha256": "abc...", "active_rev": 4 }

# List revisions, newest first
curl https://api.wauldo.com/v1/agents/AGENT_ID/revisions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "x-rapidapi-user: my-tenant"

# Rollback to a previous revision (no LLM cost, instant)
curl -X PATCH https://api.wauldo.com/v1/agents/AGENT_ID/active-revision \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "x-rapidapi-user: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{"rev": 3}'

SDK examples

# Python
from wauldo.agents import AgentsClient
agents = AgentsClient(base_url="https://api.wauldo.com", api_key="YOUR_KEY", tenant="my-tenant")

rev = agents.create_revision("AGENT_ID", custom_preset=preset_v2, message="tighten triage")
print(rev.rev, rev.sha256)

# Rollback in one line
agents.set_active_revision("AGENT_ID", rev=3)

// TypeScript
import { AgentsClient } from "wauldo";
const agents = new AgentsClient({ baseUrl: "https://api.wauldo.com", apiKey: "YOUR_KEY", tenant: "my-tenant" });

const rev = await agents.createRevision("AGENT_ID", { customPreset: presetV2, message: "tighten triage" });
await agents.setActiveRevision("AGENT_ID", 3);

// Rust
use wauldo::{AgentsClient, CreateRevisionRequest};
let agents = AgentsClient::new("https://api.wauldo.com")
    .with_api_key("YOUR_KEY")
    .with_tenant("my-tenant");

let rev = agents.create_revision("AGENT_ID", CreateRevisionRequest {
    custom_preset: preset_v2,
    message: Some("tighten triage".into()),
    set_active: true,
}).await?;

agents.set_active_revision("AGENT_ID", 3).await?;

Configure

# wauldo.toml — declared per agent
[agent]
name = "product-search"

[agent.tags]
team    = "frontend"
env     = "prod"
project = "search-relevance"
billing = "internal"

# Then create the agent normally — tags are picked up automatically.
curl -X POST https://api.wauldo.com/v1/agents \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "x-rapidapi-user: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-search",
    "wauldo_toml": "",
    "preset": "rag_grounded"
  }'

Read the metrics

Two Prometheus counters surface tagged spend (admin-scoped /metrics) :

# Cost in micro-USD broken down by tags + model
wauldo_llm_cost_by_tag_micro_usd_total{model, tag_team, tag_env, tag_project, tag_billing}

# Token volume same breakdown
wauldo_llm_tokens_by_tag_total{model, tag_team, tag_env, tag_project, tag_billing, kind}

Reliability guarantees

Endpoints

# Register a webhook for verdict alerts
curl -X POST https://api.wauldo.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "x-rapidapi-user: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/wauldo-hook",
    "events": ["verification.alert", "task.failed"],
    "secret": "whsec_your_random_secret"
  }'

# Verify a signature (Node.js example)
const crypto = require("crypto");
function verify(req) {
  const got = req.headers["x-wauldo-signature"];
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET)
    .update(req.rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}

Validation guarantees (at create time)

Runtime guarantees (at execution time)

Endpoints

Define a workflow

Three states : compute via tool:calculator, branch on the result, terminate. State type values use PascalCase ; transitions use next.

# Sequential pipeline: compute → branch → succeed
curl -X POST https://api.wauldo.com/v1/workflows \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "triage",
    "start_at": "Compute",
    "states": {
      "Compute": {
        "type": "Task",
        "resource": "tool:calculator",
        "next": "Route"
      },
      "Route": {
        "type": "Choice",
        "choices": [
          { "variable": "$.output", "operator": "contains", "value": "42", "next": "Done" }
        ],
        "default": "Done"
      },
      "Done": { "type": "Succeed" }
    }
  }'

Run it and poll

Submit the run, capture the execution_id, and poll until status reaches a terminal value (succeeded, failed, timed_out).

# Start the run (202 Accepted)
curl -X POST https://api.wauldo.com/v1/workflows/$WF_ID/runs \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "operation": "add", "a": 21, "b": 21 } }'

# → { "execution_id": "wfr_...", "workflow_id": "wf_...", "status": "running" }

# Poll the run record
curl https://api.wauldo.com/v1/workflows/$WF_ID/runs/$EXECUTION_ID \
  -H "Authorization: Bearer YOUR_KEY"

# → {
#     "execution": {
#       "id": "wfr_...",
#       "status": "succeeded",
#       "current_state": null,
#       "input":  { "operation": "add", "a": 21, "b": 21 },
#       "output": { "output": "42" },
#       "started_at": 1747...,
#       "ended_at":   1747...,
#       "error": null
#     }
# }

SDK clients

Same create → start → poll loop without writing the HTTP yourself. The wait_for_run helper polls until terminal so you get the final WorkflowExecution back directly.

from wauldo.workflows import WorkflowsClient

wf = WorkflowsClient(base_url="https://api.wauldo.com", api_key="YOUR_KEY")

created = wf.create(
    name="triage",
    start_at="Compute",
    states={
        "Compute": {"type": "Task", "resource": "tool:calculator", "next": "Done"},
        "Done": {"type": "Succeed"},
    },
)

run = wf.start_run(created.id, input={"operation": "add", "a": 21, "b": 21})
final = wf.wait_for_run(created.id, run.execution_id)
print(final.status, final.output)  # succeeded {'result': 42.0}

import { WorkflowsClient } from "wauldo";

const wf = new WorkflowsClient({ baseUrl: "https://api.wauldo.com", apiKey: "YOUR_KEY" });

const created = await wf.create({
  name: "triage",
  startAt: "Compute",
  states: {
    Compute: { type: "Task", resource: "tool:calculator", next: "Done" },
    Done: { type: "Succeed" },
  },
});

const run = await wf.startRun(created.id, { operation: "add", a: 21, b: 21 });
const final = await wf.waitForRun(created.id, run.execution_id);
console.log(final.status, final.output); // succeeded { result: 42 }

use wauldo::workflows::{CreateWorkflowRequest, WorkflowsClient};
use serde_json::json;
use std::collections::HashMap;

let wf = WorkflowsClient::new("https://api.wauldo.com")
    .with_api_key("YOUR_KEY");

let mut states = HashMap::new();
states.insert("Compute".into(), json!({"type": "Task", "resource": "tool:calculator", "next": "Done"}));
states.insert("Done".into(), json!({"type": "Succeed"}));

let created = wf.create(CreateWorkflowRequest {
    name: "triage".into(),
    start_at: "Compute".into(),
    states,
    description: None,
}).await?;

let run = wf.start_run(&created.id, Some(json!({"operation": "add", "a": 21, "b": 21}))).await?;
let final_exec = wf.wait_for_run(&created.id, &run.execution_id, None, None).await?;
println!("{} {:?}", final_exec.status, final_exec.output);

Execution record fields

JSONPath subset

Variables in Choice.variable and Task.output_path use a small JSONPath subset. Missing fields fall through to the default branch ; invalid syntax is rejected.

Endpoints

# Publish a completed run
curl -X POST https://api.wauldo.com/v1/tasks/TASK_ID/share \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "x-rapidapi-user: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{}'

# Returns: { "share_id": "r_abc...", "url": "https://wauldo.com/r/r_abc...", "expires_at": 1780797026156 }

# Anyone can read (no auth)
curl https://api.wauldo.com/v1/runs/r_abc...

# Or open the public page directly:
# https://wauldo.com/r/r_abc...

SDK examples

# Python (wauldo >= 0.13)
from wauldo.agents import AgentsClient
agents = AgentsClient(base_url="https://api.wauldo.com", api_key="YOUR_KEY", tenant="my-tenant")

share = agents.share_task("TASK_ID")
print(share.url)        # https://wauldo.com/r/r_abc...
print(share.expires_at) # epoch ms or None
agents.unshare_task("TASK_ID")

// TypeScript (wauldo >= 0.12)
import { AgentsClient } from "wauldo";
const agents = new AgentsClient({ baseUrl: "https://api.wauldo.com", apiKey: "YOUR_KEY", tenant: "my-tenant" });

const share = await agents.shareTask("TASK_ID");
console.log(share.url);
await agents.unshareTask("TASK_ID");

// Rust (wauldo >= 0.12)
use wauldo::AgentsClient;
let agents = AgentsClient::new("https://api.wauldo.com")
    .with_api_key("YOUR_KEY")
    .with_tenant("my-tenant");

let share = agents.share_task("TASK_ID").await?;
println!("{}", share.url);
agents.unshare_task("TASK_ID").await?;

Usage

from openai import OpenAI
from wauldo.openai import with_verification

client = OpenAI()                # or AsyncOpenAI, or any OpenAI-compat client
verified = with_verification(    # wraps it
    client,
    wauldo_api_key="tig_live_...",
    fact_check_mode="lexical",  # or "hybrid", "semantic"
)

response = verified.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Capital of France?"}],
)

# Standard OpenAI ChatCompletion, plus:
response.wauldo.verdict          # "SAFE" | "UNVERIFIED" | "CONFLICT" | ...
response.wauldo.support_score    # 0.94
response.wauldo.halluc_rate      # 0.0
response.wauldo.claims_count     # 7
response.wauldo.fact_check_mode  # "lexical"
response.wauldo.error            # None when verdict attached cleanly

Behavior contract

Endpoints

# Store a memory entry
curl -X POST https://api.wauldo.com/v1/memory/support-context \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "x-rapidapi-user: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{"key": "user_preference", "value": "prefers email over phone", "tags": ["contact"]}'

# Search memory
curl -X POST https://api.wauldo.com/v1/memory/support-context/search \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "x-rapidapi-user: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{"query": "contact preference", "limit": 5}'