Quickstart

By the end of this page you will have declared an element with a control and a reward, served a decision to a user, reported the outcome Curious learns from, and seen it in the dashboard. Everything runs under a test key, so nothing here touches live data.

Get a test key

In the dashboard, open Settings and create a secret test key. It starts with curious_sk_test_. Put it in your environment as CURIOUS_SECRET_KEY; it is shown once.A test key runs the whole product against shadow users: real declarations, real variants, real decisions, excluded from live learning and live metrics. See Keys and environments.

Decide what to show

The first call for an element declares it: the control is what you show today, the rewards are what success means, and element_type tells Curious what kind of content it is writing. The response is the content to render.

HTTP
Node SDK

curl https://api.trycurious.ai/v1/decide \
  -H "Authorization: Bearer $CURIOUS_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "element": "welcome_email_subject",
    "element_type": "email_subject",
    "user_id": "user_123",
    "control": "Welcome to Acme",
    "rewards": [
      { "name": "email_clicked", "window_seconds": 86400 }
    ]
  }'

{
  "content": "Welcome to Acme",
  "arm_id": "3f1c2b6e-0000-4000-8000-00000000a000",
  "arm_type": "control",
  "decision_id": "8a7b6c5d-0000-4000-8000-00000000d001",
  "experiment_id": "1e2d3c4b-0000-4000-8000-00000000e001",
  "experiment_status": "initializing"
}

@trycurious/node is built and tested but not yet published to npm, so this tab does not run yet. Use the HTTP tab until it is; everything the SDK does is documented on Raw HTTP.

npm install @trycurious/node

In a Supabase Edge Function or Deno: import { Curious } from "npm:@trycurious/node@0". Node 22 or newer, Bun and Cloudflare Workers are supported.

import { Curious } from "@trycurious/node";

const curious = new Curious({ apiKey: process.env.CURIOUS_SECRET_KEY! });

const result = await curious.decide({
  element: "welcome_email_subject",
  userId: "user_123",
  fallback: "Welcome to Acme",
  declaration: {
    elementType: "email_subject",
    control: "Welcome to Acme",
    rewards: [{ name: "email_clicked", windowSeconds: 86_400 }],
  },
});

sendEmail({ subject: result.content });
// result.served is "curious" or "fallback"; result.armId says which arm.

The first decisions serve the control while Curious generates its first variants; experiment_status moves from initializing to exploring when they are live. Send the same declaration on every call: an identical declaration is a no-op.

Report the outcome

When the user does the thing, send the event. Curious attributes it to the decision that preceded it, within the reward’s window.

HTTP
Node SDK

curl https://api.trycurious.ai/v1/events \
  -H "Authorization: Bearer $CURIOUS_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "name": "email_clicked",
    "id": "evt_8f3a"
  }'

{ "status": "success" }

id is optional and makes a retry safe: send the same request again and the response is { "status": "success", "duplicate": true }.

curious.track({ userId: "user_123", name: "email_clicked" });

// Hand delivery to your runtime before it exits or freezes:
await curious.flush(); // jobs, scripts, graceful shutdown
// EdgeRuntime.waitUntil(curious.flush()); // Supabase Edge Functions
// ctx.waitUntil(curious.flush());         // Cloudflare Workers

Confirm it worked

Open the dashboard. The element is there with its experiment, the control, and the decision and event you just sent.When the first variants appear, each with the hypothesis behind it, they wait for your approval before serving: options.approval defaults to manual. Approve them in the dashboard, or declare "options": { "approval": "auto" } to let generated variants serve as soon as they exist. See Approval.

Where next

Serve a decision

The user buckets, the declaration fields, the response, and what publishable keys may send.

Track outcomes

Event names, values, timestamps, idempotent ids and the batch form.

Fallbacks and timeouts

What a correct delivery path does when Curious is slow or down.

Go live

The checklist for switching from a test key to a live one.

The nouns behind these calls (elements, declarations, arms, rewards) are on The model.

Get started

Guides

SDKs

Concepts

Troubleshooting

Get a test key

Decide what to show

Report the outcome

Confirm it worked

Where next

Serve a decision

Track outcomes

Fallbacks and timeouts

Go live