Cookbook

Recipe 01 — Idempotent run creation

Network retries should never double-execute. Pass an Idempotency-Key; the same key within 24 hours returns the original run.

await mynd.runs.create(
  { model: "y0-fast", prompt: "File this receipt.", files: [fileId] },
  { idempotencyKey: `receipt-${fileId}` },
);

Recipe 02 — Gate outputs with a judge

Score every production output against a rubric before it leaves your system. Below threshold, route to a human.

const judgment = await mynd.evaluations.create({
  model: "y0-judge",
  run_id: run.id,
  rubric: "rb_faithfulness_v2",
  threshold: 0.8,
});
if (!judgment.passed) await queueForReview(run.id);

Recipe 03 — Batch embeddings on write

Embed at ingestion, not at query time. Batch up to 2,048 inputs per call and store the model version next to the vector.

const { embeddings, model_version } = await mynd.embeddings.create({
  model: "y0-embed-l",
  input: documents.map((d) => d.text),
  dimensions: 1536,
});

Recipe 04 — Verify webhooks before trusting them

Every webhook delivery is signed. Verify the signature before touching the payload — see the webhooks topic for the full scheme.

const event = mynd.webhooks.verify(
  rawBody,
  req.headers["mynd-signature"],
  process.env.MYND_WEBHOOK_SECRET,
); // throws on bad signature

Recipe 05 — Replay a trace in CI

Pin a suite of known-good traces and replay them on every deploy. TraceReplay is byte-stable across releases; a diff means your prompt or context changed.

mynd traces export run_4af2c19e > fixtures/thursday-brief.trace.json
mynd traces replay fixtures/*.trace.json --fail-on-diff

Recipe 06 — Scope keys per service

One key per deployable service, scoped to exactly what it does. The billing worker gets finance:read and runs:write; nothing else. When the audit log shows an access, the key name tells you which service made it.

• ↳Name keys after services, not people
• ↳Grant context scopes per source, never wildcard
• ↳Alert on scope_denied — it is either a bug or a probe