Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agents.candu.ai/llms.txt

Use this file to discover all available pages before exploring further.

Every action has a policy answering three questions: who can trigger it, when it requires confirmation, and what role conditions apply.

​
Governance tiers

​
Automatic

The action runs immediately. Use for all read actions, lookups, and autocomplete calls the AI makes silently.

​
Confirm required

The AI prepares the full payload, then pauses. The user sees a confirmation panel before anything executes. Use for anything that creates, modifies, or deletes data.
When in doubt, use Confirm required. It costs the user one click. It prevents a category of mistakes that are expensive to undo.

​
Roles

Roles in Candu Actions are a product-layer guardrail: they decide which actions appear to a given user. They are not a security boundary. Your API must enforce its own access controls — Candu’s role check just prevents the AI from offering an action the user shouldn’t see in the first place.

​
How role-gating works

There is no separate role parameter. You pass the user’s role as a key inside the identifiers object at init() time: 
window.canduAgentik.init({
  userId: "user-123",
  clientToken: "YOUR_CLIENT_TOKEN",
  snippetVersion: "0.2.0",
  identifiers: {
    role: "admin"   // matches role configured on each action
  }
});
Candu Actions compares the role value against the roles configured on each action in the dashboard. Users always have access to actions configured for Everyone regardless of their role. Actions configured for a specific role are only available when the identifier value matches.
RoleWho can trigger it
EveryoneAll users, always
ManagerUsers where identifiers.role === "manager"
AdminUsers where identifiers.role === "admin"
Role values are arbitrary strings — these are illustrative. Configure whichever role names match your app’s existing user types. If no role is passed, or the value doesn’t match any configured role, the user still has access to all Everyone actions. Role gating is evaluated per request. A user whose role changes mid-session will see the available actions update at their next message.

​
Identifiers

Identifiers are runtime context values you pass to Candu Actions at init() time. It’s a free-form key-value object — anything the AI might need at runtime that isn’t user-specific. 
window.canduAgentik.init({
  userId: "user-123",           // required
  clientToken: "YOUR_TOKEN",    // required
  snippetVersion: "0.2.0",      // required
  identifiers: {                // optional
    role: "admin",
    organizationId: "org-456",
    workspaceSlug: "my-workspace"
  }
});
Beyond gating, identifiers do real work at runtime. Any key in the identifiers object is available as a {variable} in action endpoint templates — /api/{organizationId}/segments resolves at request time from identifiers.organizationId. This is how you keep action definitions tenant-agnostic. Identifiers are injected into the AI’s system prompt on every request. They are never written to any database — they’re request-scoped only and discarded when the request completes.

​
Data and privacy

DataPersisted
userIdYes — used to group runs in the Activity view
IdentifiersNo — request-scoped only
User message textYes
Action inputs and outputsYes (as JSON)
Config filesYes — retained until deleted
If your API returns sensitive data in a response body, that data will appear in execution logs. Design your action endpoints to return the minimum necessary response. See Execution & Logs for the full field reference.