Cookbook

How to set up Cadreen with setup sessions

Setup sessions let you accumulate connections, credentials, memory, and policies — then apply them all at once. Use them when onboarding a new workspace or configuring Cadreen for a new use case.

When to use sessions vs. stateless setup

Cadreen has two ways to set up resources. The stateless /setup endpoint applies each resource immediately. Setup sessions let you stage changes and apply them atomically.

Use stateless setup when

You're adding a single resource — one connection, one credential, one memory item. Quick and direct.

Use sessions when

You're setting up a whole use case — multiple connections, credentials, policies, and memory items that should all land together or not at all.

Note

Sessions are atomic. If any resource fails to apply, the session records what failed and what succeeded. You can inspect the result and retry only the failures.

Create a session

Start by creating a session with an optional purpose. The session starts in draft status — you can add resources to it without anything taking effect yet.

BASH

# Create a session
curl -X POST \
  -H "Authorization: Bearer sk_cadreen_..." \
  -H "Content-Type: application/json" \
  -d '{"purpose": "Set up ecommerce support"}' \
  https://accomplishanything.today/api/v1/cadreen/setup/sessions

JSON

{
  "id": "sess_abc123",
  "status": "draft",
  "purpose": "Set up ecommerce support",
  "connections": [],
  "credentials": [],
  "memory": [],
  "policies": [],
  "applied_count": 0,
  "failed_count": 0,
  "created_at": "2026-06-25T10:00:00Z"
}

Add resources to the session

Add connections, credentials, memory items, and policies to the session. You can call this endpoint multiple times — resources accumulate.

BASH

# Add a connection and a memory item
curl -X POST \
  -H "Authorization: Bearer sk_cadreen_..." \
  -H "Content-Type: application/json" \
  -d '{
    "connections": [{"capability": "stripe"}],
    "memory": [
      {
        "type": "reference",
        "content": {"text": "Refunds over $500 require manager approval"},
        "domain": "finance"
      }
    ],
    "policies": [
      {
        "name": "refund-limit",
        "rule": "amount > 500 requires approval",
        "severity": "high"
      }
    ]
  }' \
  https://accomplishanything.today/api/v1/cadreen/setup/sessions/sess_abc123

JSON

{
  "id": "sess_abc123",
  "status": "draft",
  "connections": [{"capability": "stripe"}],
  "memory": [{"type": "reference", "content": {"text": "Refunds over $500 require manager approval"}}],
  "policies": [{"name": "refund-limit", "rule": "amount > 500 requires approval"}]
}

Review before applying

Fetch the session to see everything you've staged. Check the resource lists, verify the purpose, and make sure nothing unexpected snuck in.

BASH

curl -H "Authorization: Bearer sk_cadreen_..." \
  https://accomplishanything.today/api/v1/cadreen/setup/sessions/sess_abc123

The response includes connections, credentials, memory, and policies arrays showing exactly what will be applied. The session stays in draft until you explicitly apply.

Apply the session

When you're ready, apply the session. The confirm: true flag is required — it's a safety mechanism to prevent accidental application.

BASH

curl -X POST \
  -H "Authorization: Bearer sk_cadreen_..." \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}' \
  https://accomplishanything.today/api/v1/cadreen/setup/sessions/sess_abc123/apply

JSON

{
  "session_id": "sess_abc123",
  "status": "applied",
  "applied": 3,
  "failed": 0
}

Note

If any resource fails, the session records both applied and failed counts. Successfully applied resources stay — only the failures need retry.

Session lifecycle

Sessions move through four statuses. Once applied or failed, a session is read-only — you can't add more resources to it.

SDK examples

All three SDKs support setup sessions. Here's the same workflow in TypeScript, Python, and Go.

TypeScript

TYPESCRIPT

import { CadreenClient } from "@cadreen/sdk";

const cadreen = new CadreenClient({ apiKey: "sk_cadreen_..." });

// Create a session
const session = await cadreen.setup.sessions.create({
  purpose: "Set up ecommerce support",
});

// Add resources
await cadreen.setup.sessions.add(session.id, {
  connections: [{ capability: "stripe" }],
  memory: [{
    type: "reference",
    content: { text: "Refunds over $500 require manager approval" },
    domain: "finance",
  }],
  policies: [{
    name: "refund-limit",
    rule: "amount > 500 requires approval",
  }],
});

// Apply
const result = await cadreen.setup.sessions.apply(session.id, { confirm: true });
console.log(result.status); // "applied"
console.log(result.applied); // 3

Python

PYTHON

from cadreen_sdk import CadreenClient

cadreen = CadreenClient(api_key="sk_cadreen_...")

# Create a session
session = cadreen.setup.sessions.create(purpose="Set up ecommerce support")

# Add resources
cadreen.setup.sessions.add(session.id, connections=[{"capability": "stripe"}], memory=[{
    "type": "reference",
    "content": {"text": "Refunds over $500 require manager approval"},
    "domain": "finance",
}], policies=[{
    "name": "refund-limit",
    "rule": "amount > 500 requires approval",
}])

# Apply
result = cadreen.setup.sessions.apply(session.id, confirm=True)
print(result.status)   # "applied"
print(result.applied)  # 3

package main

import (
    "fmt"
    cadreen "github.com/timothy-billingrails/cadreen-sdks/go/cadreen"
)

func main() {
    client := cadreen.NewClient("sk_cadreen_...")

    // Create a session
    session, _ := client.Setup.Sessions.Create(cadreen.SessionCreateRequest{
        Purpose: "Set up ecommerce support",
    })

    // Add resources
    client.Setup.Sessions.Add(session.ID, cadreen.SessionAddRequest{
        Connections: []cadreen.Connection{{Capability: "stripe"}},
        Memory: []cadreen.MemoryItem{{
            Type:    "reference",
            Content: map[string]any{"text": "Refunds over $500 require manager approval"},
            Domain:  "finance",
        }},
    })

    // Apply
    result, _ := client.Setup.Sessions.Apply(session.ID, cadreen.SessionApplyRequest{
        Confirm: true,
    })
    fmt.Println(result.Status)  // "applied"
    fmt.Println(result.Applied) // 3
}

Error handling

Sessions can fail partially. When you apply, some resources might succeed while others fail. The response tells you exactly what happened.

400 — confirm_required

You must pass confirm: true to apply. This prevents accidental application.

409 — invalid_status

The session is already applied or failed. Only draft sessions can be applied.

Partial failure

If failed > 0, inspect the session to see which resources failed. Successfully applied resources remain — only failures need retry.

JSON

{
  "session_id": "sess_abc123",
  "status": "applied",
  "applied": 2,
  "failed": 1
}

Note

Always check failed in the apply response. If it's greater than zero, fetch the session to see which resources didn't apply and why.