SigWise
View as Markdown Open in ClaudeOpen in ChatGPT

Quickstart ​

From an API key to your first answer in five minutes.

1. Get an API key ​

Sign up in the console, open API keys and create a key. You get two values:

  • a key ID like 7Hx2Qp9LmZ, which identifies the key;
  • a signing secret like your_secret, shown only once. Keep it on your server.
bash
export ANALYZE_API_KEY=your_key_id
export ANALYZE_SECRET=your_secret

Every account starts with free credit and three signals (is_scammer, trust_score and buyer_intent), so you can send events right away.

2. Set up a client ​

Requests are authenticated with a short-lived token signed with your secret (see Authentication). The SDKs sign each request for you. With plain HTTP, a small shell function does it:

bash
# Signs a JWT with $ANALYZE_SECRET that is valid for five minutes.
b64url() { openssl base64 -A | tr '+/' '-_' | tr -d '='; }
sign() {
  local now=$(date +%s) h p
  h=$(printf '{"alg":"HS256","typ":"JWT"}' | b64url)
  p=$(printf '{"iat":%d,"exp":%d}' "$now" "$((now + 300))" | b64url)
  printf '%s.%s.%s' "$h" "$p" \
    "$(printf '%s.%s' "$h" "$p" | openssl dgst -sha256 -hmac "$ANALYZE_SECRET" -binary | b64url)"
}
API=https://api.sigwise.ai
ts
import { SigWise } from "@sigwise/sdk";

// Reads ANALYZE_API_KEY and ANALYZE_SECRET.
const sigwise = new SigWise();
python
from sigwise import SigWise

# Reads ANALYZE_API_KEY and ANALYZE_SECRET.
sigwise = SigWise()
go
import sigwise "github.com/sigwise/sigwise-go"

// Empty values fall back to ANALYZE_API_KEY and ANALYZE_SECRET.
client := sigwise.New("", "")
php
// Null arguments fall back to ANALYZE_API_KEY and ANALYZE_SECRET.
$sigwise = new SigWise\Client();

SDKs

The SDKs are coming soon to npm, PyPI, the Go module proxy and Packagist. Until then, use the cURL tab: the same requests work from any HTTP client.

3. Send events ​

Send what happens to an object. Here, a message from user-42:

bash
curl -X POST "$API/v1/objects/user-42/events?api_key=$ANALYZE_API_KEY" \
  -H "Authorization: Bearer $(sign)" -H 'Content-Type: application/json' \
  -d '{"object_type":"user","events":[
        {"type":"event","name":"profile.updated","metadata":{"field":"bio"}},
        {"type":"message","content":"is this still available? can I pay by wire?"}
      ]}'
ts
await sigwise.events.ingest("user-42", {
  object_type: "user",
  events: [
    { type: "event", name: "profile.updated", metadata: { field: "bio" } },
    { type: "message", content: "is this still available? can I pay by wire?" },
  ],
});
python
sigwise.events.ingest(
    "user-42",
    object_type="user",
    events=[
        {"type": "event", "name": "profile.updated", "metadata": {"field": "bio"}},
        {"type": "message", "content": "is this still available? can I pay by wire?"},
    ],
)
go
_, err := client.Events.Ingest(ctx, "user-42", &sigwise.IngestRequest{
	ObjectType: sigwise.String("user"),
	Events: []sigwise.EventInput{
		{Type: sigwise.EventTypeEvent, Name: sigwise.String("profile.updated"), Metadata: sigwise.Metadata{"field": "bio"}},
		{Type: sigwise.EventTypeMessage, Content: sigwise.String("is this still available? can I pay by wire?")},
	},
})
php
$sigwise->events->ingest('user-42', [
    'object_type' => 'user',
    'events' => [
        ['type' => 'event', 'name' => 'profile.updated', 'metadata' => ['field' => 'bio']],
        ['type' => 'message', 'content' => 'is this still available? can I pay by wire?'],
    ],
]);

The API answers 202 Accepted and schedules an analysis a few seconds later:

json
{ "object_id": "user-42", "accepted": 2, "analysis_status": "scheduled", "analysis_delay_ms": 5000 }

4. Read the answers ​

bash
curl "$API/v1/objects/user-42?api_key=$ANALYZE_API_KEY" -H "Authorization: Bearer $(sign)"
ts
const object = await sigwise.objects.get("user-42");
console.log(object.analysis, object.pending);
python
obj = sigwise.objects.get("user-42")
print(obj["analysis"], obj["pending"])
go
obj, err := client.Objects.Get(ctx, "user-42")
php
$object = $sigwise->objects->get('user-42');

analysis holds the latest answer for each signal; pending lists the signals that have no answer yet. Right after ingesting, everything is pending until the analysis runs.

5. Ask your own question ​

Add a signal with PUT /v1/signals/{key}. It is used from the next analysis on:

bash
curl -X PUT "$API/v1/signals/wants_refund?api_key=$ANALYZE_API_KEY" \
  -H "Authorization: Bearer $(sign)" -H 'Content-Type: application/json' \
  -d '{"type":"noul","instructions":"Is this customer asking for a refund?",
       "criteria":{"true":"asks for money back","false":"anything else"}}'
ts
await sigwise.signals.upsert("wants_refund", {
  type: "noul",
  instructions: "Is this customer asking for a refund?",
  criteria: { true: "asks for money back", false: "anything else" },
});
python
sigwise.signals.upsert(
    "wants_refund",
    type="noul",
    instructions="Is this customer asking for a refund?",
    criteria={"true": "asks for money back", "false": "anything else"},
)
go
_, err := client.Signals.Upsert(ctx, "wants_refund", &sigwise.SignalInput{
	Type:         sigwise.SignalTypeNoul,
	Instructions: "Is this customer asking for a refund?",
	Criteria:     map[string]string{"true": "asks for money back", "false": "anything else"},
})
php
$sigwise->signals->upsert('wants_refund', [
    'type' => 'noul',
    'instructions' => 'Is this customer asking for a refund?',
    'criteria' => ['true' => 'asks for money back', 'false' => 'anything else'],
]);

Existing objects are not re-analyzed automatically, since each analysis is billed. To answer the new signal for them, start a backfill.

Next ​