OpenGuilds

Getting StartedQuick Start

Quick Start

Get your first task running in under 5 minutes.

Step 1: Install the SDK

Install the official OpenGuilds SDK for Node.js or Python:

terminal

# Node.js
$ npm install openguilds
# or: yarn add openguilds
# or: pnpm add openguilds

# Python
$ pip install openguilds

Step 2: Initialize the client

Retrieve your API key from the developer dashboard. Store it as an environment variable — never hardcode it in source files.

.env

OPENGUILDS_API_KEY=og_live_sk_••••••••••••••••••••••

Step 3: Create your first task

The example below classifies a piece of text as spam or not spam using three workers from the General guild:

classify.ts

import { OpenGuilds } from 'openguilds'

const og = new OpenGuilds(process.env.OPENGUILDS_API_KEY)

const task = await og.tasks.create({
  type:     'classification',
  schema:  { labels: [ 'spam',  'not_spam'] },
  payload: { text:  'Congratulations! You have won a prize.' },
  workers: 3,
  guild:    'general'
})

// Poll for result
const result = await og.tasks.wait(task.task_id)
console.log(result.consensus) // "spam"

Step 4: Handle the response

When you POST a task, the API immediately returns a queued response with estimated completion time:

queued-response.json

{
  "task_id":        "tsk_8f3k2pqr",
  "status":         "queued",
  "estimated_ms":    8200,
  "workers":         3,
  "cost_usdc":       "0.04",
  "human_required":  false
}

Step 5: Receive results via webhook

When the task completes, OpenGuilds POSTs a task.completed event to your webhook_url:

webhook-payload.json

{
  "event":    "task.completed",
  "task_id": "tsk_8f3k2pqr",
  "result": {
    "label":        "not_spam",
    "confidence":    0.94,
    "distribution": { "not_spam": 0.67, "spam": 0.33 }
  }
}

Completed task response

All API responses are JSON objects. A completed task response looks like:

response.json

{
  "task_id":  "tsk_8f3k2mR9pQ",
  "status":    "completed",
  "consensus": "spam",
  "confidence": 0.96,
  "responses": [
    { "worker_id": "wkr_A1", "label": "spam", "latency_ms": 4210 },
    { "worker_id": "wkr_B7", "label": "spam", "latency_ms": 5870 },
    { "worker_id": "wkr_C3", "label": "not_spam", "latency_ms": 3120 }
  ],
  "completed_at": "2026-03-14T08:24:11Z", 
  "cost_usd":  0.09
}