Core Concepts

Workflows

A workflow is the atomic unit of execution in WeaveOS. Every AI task — a ticket resolution, a document summary, a pricing decision — runs as a workflow with a quoted price, real-time cost tracking, and on-chain settlement.

Workflow object

json

{
  "id": "wf_e4rgffg44fg4g44",
  "status": "Settled",
  "product": "ticket_resolution_v2",
  "customerId": "cus_acme_prod_01",
  "payload": {
    "ticketId": "TKT-8821",
    "subject": "Can't export data to CSV"
  },
  "quoted": {
    "amount": 0.12,
    "currency": "USD",
    "model": "fixed"
  },
  "billed": {
    "amount": 0.034,
    "breakdown": {
      "model":   0.021,
      "tools":   0.008,
      "compute": 0.005,
      "human":   0.000
    }
  },
  "margin": {
    "achieved": 0.717,
    "floor":    0.40
  },
  "settlement": {
    "txId":    "BjRVtMx3k9...sui",
    "blobId":  "GzPQ...walrus",
    "settledAt": "2026-05-21T14:32:10Z"
  },
  "createdAt": "2026-05-21T14:31:54Z"
}

Lifecycle states

A workflow moves through the following states:

State	Description
`Quoted`	Workflow created. Price agreed. Awaiting execution.
`Executing`	Agent is running. Costs are being tracked in real time.
`Settled`	Execution complete. Outcome validated. Settlement written on-chain.
`Disputed`	A party has raised a dispute within the dispute window.
`Refunded`	Dispute resolved in the customer's favour. Payment reversed.

Create a workflow

POST/v1/workflows

Creates a new workflow and returns an upfront quote.

javascript

const workflow = await client.workflows.create({
  product:    "ticket_resolution_v2",  // Your product identifier
  customerId: "cus_acme_prod_01",      // Customer in your system
  payload:    { ticketId: "TKT-8821", subject: "Export issue" },
});

// workflow.id            → "wf_e4rgffg44fg4g44"
// workflow.quoted.amount → 0.12  (USD, before execution)

Request parameters

Parameter	Type	Required	Description
`product`	string	Yes	Product identifier. Must match a configured product in your account.
`customerId`	string	Yes	Your customer's identifier. Used for cost attribution and reporting.
`payload`	object	Yes	Input data for the AI task. Shape is defined by the product config.
`metadata`	object	No	Arbitrary key-value pairs attached to the workflow for your own use.

List workflows

GET/v1/workflows

javascript

const workflows = await client.workflows.list({
  status: "Settled",   // Optional: filter by state
  limit:  25,          // Optional: 1–100, default 20
  after:  "wf_abc...", // Optional: cursor for pagination
});

// workflows.data  → array of workflow objects
// workflows.next  → cursor for next page (null if last page)

Fetch a workflow

GET/v1/workflows/:id

javascript

const workflow = await client.workflows.fetch("wf_e4rgffg44fg4g44");
console.log(workflow.status);           // "Settled"
console.log(workflow.margin.achieved);  // 0.717

Cost tracking

WeaveOS breaks down the cost of every workflow across four layers. This breakdown is available on the billed.breakdown field once the workflow reaches Settled state:

Layer	What it covers
`model`	LLM provider token costs — input and output, across all model calls in the workflow.
`tools`	Third-party tool call fees — search APIs, data providers, external integrations.
`compute`	Infrastructure overhead — embeddings, vector search, retrieval, orchestration.
`human`	Human-in-the-loop costs — review, escalation, approval steps.

NoteThe margin.floor field reflects the minimum acceptable margin configured for this product. If a workflow's achieved margin drops below the floor, a guardrail alert fires — or execution is paused, depending on your configuration.

Workflow events

WeaveOS emits events at each lifecycle transition. Subscribe to them via webhooks — see Webhooks.

Event	Fired when
`workflow.started`	Execution begins — status moves to Executing.
`workflow.completed`	Outcome validated and settlement written on-chain.
`workflow.failed`	Execution failed without a settleable outcome.
`dispute.raised`	A dispute is opened within the dispute window.
`dispute.resolved`	A dispute is resolved (for or against).

Authentication Quotes & Pricing