Getting Started

Quickstart

Create and price your first AI workflow in under five minutes.

1. Install the SDK

Install the WeaveOS Node.js SDK from npm. Python and cURL are also supported — see SDKs.

bash

npm install @weaveos/sdk

2. Get your API key

Navigate to Dashboard → Developer → API Keys and create a new key. Copy the secret — it will only be shown once.

Store it as an environment variable. Never commit it to source control.

bash

export WEAVEOS_API_KEY=sk_test_your_key_here

NoteUse sk_test_ keys during development. They behave identically to live keys but settlement is simulated against Sui testnet and no real charges occur.

3. Create your first workflow

Call workflows.create() with a product identifier, a customer ID, and the input payload for your AI task. WeaveOS returns an upfront quote — the price agreed before execution begins.

javascript

import WeaveOS from "@weaveos/sdk";

const client = new WeaveOS({
  apiKey: process.env.WEAVEOS_API_KEY,
});

const workflow = await client.workflows.create({
  product: "ticket_resolution_v2",
  customerId: "cus_acme_prod_01",
  payload: {
    ticketId: "TKT-8821",
    subject: "Can't export data to CSV",
    body: "When I click Export, nothing happens...",
    priority: "high",
  },
});

console.log(workflow.id);              // wf_e4rgffg44fg4g44
console.log(workflow.quoted.amount);   // 0.12
console.log(workflow.quoted.currency); // USD

4. Execute your workflow

Once a workflow is created and priced, your agent or pipeline runs the underlying task. WeaveOS tracks costs in real time across all cost layers — model inference, tool calls, compute, and human-in-the-loop — as execution proceeds.

When execution completes, submit the outcome:

javascript

// After your agent completes the task
const result = await client.workflows.complete(workflow.id, {
  outcome: {
    resolved: true,
    resolution: "Guided user to export via Settings > Data > Export CSV.",
    satisfactionScore: 4.8,
  },
});

console.log(result.status);          // "Settled"
console.log(result.margin.achieved); // 0.71  (71% margin)
console.log(result.settlement.txId); // Sui transaction ID

5. Listen for events

Use webhooks to receive real-time notifications on workflow state changes. Register a webhook endpoint in Dashboard → Developer → Webhooks, then handle events in your server:

javascript

import express from "express";
const app = express();

app.post("/webhooks/weaveos", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["weaveos-signature"];

  let event;
  try {
    event = client.webhooks.construct(req.body, sig, process.env.WEBHOOK_SECRET);
  } catch (err) {
    return res.status(400).send("Signature verification failed");
  }

  switch (event.type) {
    case "workflow.completed":
      console.log("Workflow settled:", event.data.workflowId);
      console.log("Net margin:", event.data.margin.achieved);
      break;

    case "dispute.raised":
      console.log("Dispute opened on:", event.data.workflowId);
      break;
  }

  res.json({ received: true });
});

TipDuring development, use the Test delivery button in the dashboard to send sample events to your local server without needing a production workflow.

Next steps

AuthenticationAPI keys, environments, rate limits.WorkflowsLifecycle states and execution model.Quotes & PricingPricing models and success criteria.WebhooksEvents, signatures, and retries.

Introduction Authentication

2. Get your API key

Navigate to Dashboard → Developer → API Keys and create a new key. Copy the secret — it will only be shown once.

Store it as an environment variable. Never commit it to source control.

bash

export WEAVEOS_API_KEY=sk_test_your_key_here

NoteUse sk_test_ keys during development. They behave identically to live keys but settlement is simulated against Sui testnet and no real charges occur.

3. Create your first workflow

Call workflows.create() with a product identifier, a customer ID, and the input payload for your AI task. WeaveOS returns an upfront quote — the price agreed before execution begins.

javascript

import WeaveOS from "@weaveos/sdk";

const client = new WeaveOS({
  apiKey: process.env.WEAVEOS_API_KEY,
});

const workflow = await client.workflows.create({
  product: "ticket_resolution_v2",
  customerId: "cus_acme_prod_01",
  payload: {
    ticketId: "TKT-8821",
    subject: "Can't export data to CSV",
    body: "When I click Export, nothing happens...",
    priority: "high",
  },
});

console.log(workflow.id);              // wf_e4rgffg44fg4g44
console.log(workflow.quoted.amount);   // 0.12
console.log(workflow.quoted.currency); // USD

4. Execute your workflow

When execution completes, submit the outcome:

javascript

// After your agent completes the task
const result = await client.workflows.complete(workflow.id, {
  outcome: {
    resolved: true,
    resolution: "Guided user to export via Settings > Data > Export CSV.",
    satisfactionScore: 4.8,
  },
});

console.log(result.status);          // "Settled"
console.log(result.margin.achieved); // 0.71  (71% margin)
console.log(result.settlement.txId); // Sui transaction ID

5. Listen for events

Use webhooks to receive real-time notifications on workflow state changes. Register a webhook endpoint in Dashboard → Developer → Webhooks, then handle events in your server:

javascript

import express from "express";
const app = express();

app.post("/webhooks/weaveos", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["weaveos-signature"];

  let event;
  try {
    event = client.webhooks.construct(req.body, sig, process.env.WEBHOOK_SECRET);
  } catch (err) {
    return res.status(400).send("Signature verification failed");
  }

  switch (event.type) {
    case "workflow.completed":
      console.log("Workflow settled:", event.data.workflowId);
      console.log("Net margin:", event.data.margin.achieved);
      break;

    case "dispute.raised":
      console.log("Dispute opened on:", event.data.workflowId);
      break;
  }

  res.json({ received: true });
});

TipDuring development, use the Test delivery button in the dashboard to send sample events to your local server without needing a production workflow.