Declare ahead of traffic

curl https://api.trycurious.ai/v1/declare \
  -H "Authorization: Bearer $CURIOUS_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "element": "pricing_hero",
    "element_type": "hero",
    "control": "Ship better experiments without manual analysis",
    "rewards": [{ "name": "signed_up", "window_seconds": 604800 }],
    "format": { "type": "text", "max_characters": 90 },
    "instructions": "Clear, credible, and specific. No hype.",
    "options": { "assignment": "static" }
  }'

{
  "element_id": "5c4d3e2f-0000-4000-8000-00000000f001",
  "experiment_id": "1e2d3c4b-0000-4000-8000-00000000e001",
  "experiment_status": "initializing"
}

When to use it

• Before browser traffic. A publishable key can only decide for an element that already has a live experiment; declare is how a setup script or a deploy step provisions it, with no invented user.
• Setup separate from serving. When configuration lives with your release process and the serving code should carry nothing but the element name and the user.
• Review-driven change. A declaration change that supersedes an experiment is deliberate; making it in one place, on purpose, is easier to review than finding it in a request builder.

Rules

• Secret keys only. A publishable key gets a 403 with Declare requires a secret key.
• user_id, identifiers, attributes, context and idempotency_key are a 400 here: there is no user and no decision to attach them to. There is no batch form; declare each element with its own call.
• Idempotent: an identical declaration changes nothing and returns the current experiment, so a deploy step can run it on every release. A declaration-class change supersedes through the normal chain; a mutable change applies in place; see Declarations.
• warnings appears only when there is something to say, with the same codes as decide, for example a declared arm skipped for failing validation.

In a deploy step

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

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

await curious.declare({
  element: "pricing_hero",
  elementType: "hero",
  control: "Ship better experiments without manual analysis",
  rewards: [{ name: "signed_up", windowSeconds: 7 * 86_400 }],
  format: { type: "text", max_characters: 90 },
  options: { assignment: "static" },
});