SDK Documentation

claw.guard(context)

Evaluate guard policies for a proposed action. Call this before risky operations. The guard response includes a `learning` field with historical performance context when available (recent scores, drift status, learned patterns, feedback summary). With a non_fabrication policy active, pass `content` + `sourceOfTruth` to verify outbound text before it goes out — a violation blocks (or routes to approval) and is returned under `non_fabrication` with a signed, re-verifiable receipt.

Returns: Promise<{ decision: string, reasons: string[], risk_score: number, agent_risk_score: number | null, non_fabrication?: object[] }>

const result = await claw.guard({ action_type: 'deploy', risk_score: 85 });

claw.getSignals() / claw.get_signals()

Get current risk signals across all agents.

Returns: Promise<{ signals: Object[] }>

const { signals } = await claw.getSignals();

claw.heartbeat(status, metadata) / claw.heartbeat(status=..., metadata=...)

Report agent presence and health to the control plane. Call periodically to indicate the agent is alive.

await claw.heartbeat('online', { cycle: 42, uptime_ms: 360000 });

claw.reportConnections(connections) / claw.report_connections(connections)

Report active provider connections and their status. Appears in the agent's Fleet profile.

await claw.reportConnections([
  { name: 'OpenAI', type: 'llm', status: 'connected' },
  { name: 'Postgres', type: 'database', status: 'connected' },
]);

claw.registerOpenLoop(actionId, type, desc) / claw.register_open_loop(...)

Register an unresolved dependency for a decision. Open loops track work that must be completed before the decision is fully resolved.

await claw.registerOpenLoop(action_id, 'validation', 'Waiting for PR review');

claw.resolveOpenLoop(loopId, status, res) / claw.resolve_open_loop(...)

Resolve a pending loop.

await claw.resolveOpenLoop(loop_id, 'completed', 'Approved');

claw.recordAssumption(asm) / claw.record_assumption(asm)

Record what the agent believed to be true when making a decision.

await claw.recordAssumption({ action_id, assumption: 'User is authenticated' });

claw.getLearningVelocity() / claw.get_learning_velocity()

Compute learning velocity (rate of score improvement) for agents.

Returns: Promise<{ velocity: Array<Object> }>

const { velocity } = await claw.getLearningVelocity();

claw.getLearningCurves() / claw.get_learning_curves()

Compute learning curves per action type to measure efficiency gains.

const curves = await claw.getLearningCurves();

claw.getLessons({ actionType, limit }) / claw.get_lessons(action_type=..., limit=...)

Fetch consolidated lessons from scored outcomes — what DashClaw has learned about this agent's performance patterns.

Returns: Promise<{ lessons: Object[], drift_warnings: Object[], agent_id: string }>

const { lessons, drift_warnings } = await claw.getLessons({ actionType: 'deploy' });
lessons.forEach(l => console.log(l.guidance));

claw.recordDecision(entry)

Record a decision/outcome into the learning ledger so the governance loop improves over time. agent_id is auto-injected from the constructor's agentId when omitted. Node SDK only.

Returns: Promise<{ decision: Object }>

const { decision } = await claw.recordDecision({
  decision: 'Rolled back the auth-service deploy',
  context: 'The new deploy raised the error rate',
  reasoning: 'Faster recovery than a forward fix',
  outcome: 'Error rate returned to baseline',
  confidence: 0.9
});

claw.getLearningRecommendations(filters)

Read learned recommendations for an agent/action_type from the learning ledger. agent_id defaults to the constructor's agentId when omitted. Node SDK only.

const recs = await claw.getLearningRecommendations({
  action_type: 'deploy',
  include_metrics: true,
  lookback_days: 30
});

claw.renderPrompt() / claw.render_prompt()

Fetch rendered prompt from DashClaw.

const { rendered } = await claw.renderPrompt({
  template_id: 'marketing',
  variables: { company: 'Apple' }
});

claw.listPromptTemplates(filters)

List prompt templates. Node SDK only.

Returns: Promise<{ templates: Object[] }>

const { templates } = await claw.listPromptTemplates({ category: 'marketing' });

claw.getPromptTemplate(templateId)

Fetch a single template by id. Node SDK only.

const template = await claw.getPromptTemplate('marketing');

claw.createPromptTemplate({ name, description, category })

Create a template (admin). Node SDK only.

Returns: Promise<{ id, name, description, category }>

const tpl = await claw.createPromptTemplate({
  name: 'Cold outreach',
  description: 'First-touch sales email',
  category: 'sales'
});

claw.updatePromptTemplate(templateId, patch)

Update a template's name, description, or category (admin). Node SDK only.

await claw.updatePromptTemplate('marketing', { category: 'growth' });

claw.deletePromptTemplate(templateId)

Delete a template along with its versions and runs (admin). Node SDK only.

Returns: Promise<{ deleted: true }>

await claw.deletePromptTemplate('marketing');

claw.listPromptVersions(templateId)

List a template's versions, newest first. Node SDK only.

Returns: Promise<{ versions: Object[] }>

const { versions } = await claw.listPromptVersions('marketing');

claw.createPromptVersion(templateId, { content, model_hint, parameters, changelog })

Create a new version for a template (admin). Node SDK only.

await claw.createPromptVersion('marketing', {
  content: 'Write a launch post for {{company}}.',
  model_hint: 'claude-sonnet',
  changelog: 'Initial draft'
});

claw.getPromptVersion(templateId, versionId)

Fetch a single version of a template. Node SDK only.

const version = await claw.getPromptVersion('marketing', 'v3');

claw.activatePromptVersion(templateId, versionId)

Activate a version (admin). Activating one version deactivates the others for that template, so it becomes the version renderPrompt resolves. Node SDK only.

await claw.activatePromptVersion('marketing', 'v3');

claw.getPromptStats(filters)

Prompt usage analytics. Node SDK only.

const stats = await claw.getPromptStats({ template_id: 'marketing' });

claw.listPromptRuns(filters)

List recorded prompt runs. Node SDK only.

const runs = await claw.listPromptRuns({ template_id: 'marketing', limit: 20 });

claw.createScorer(name, type, config) / claw.create_scorer(...)

Create a reusable scorer definition for automated evaluation.

await claw.createScorer('toxicity', 'regex', { pattern: 'bad-word' });

claw.previewScorer({ scorer_type, config, sample })

Dry-run a scorer config against a sample without persisting anything — no eval_scores row is written. Use it to validate a quality gate before wiring the scorer into a profile. Node SDK only.

Returns: Promise<{ preview, scorer_type, result: { score, label, reasoning, error } }>

const { result } = await claw.previewScorer({
  scorer_type: 'regex',
  config: { pattern: 'bad-word' },
  sample: { output: 'this contains a bad-word' }
});
console.log(result.score, result.label);

claw.createScoringProfile(config) / claw.create_scoring_profile(...)

Define weighted quality scoring profiles across multiple scorers.

await claw.createScoringProfile({ 
  name: 'prod-quality', 
  dimensions: [{ scorer: 'toxicity', weight: 0.5 }] 
});

claw.simulatePolicy({ policy_type, rules, days })

Side-effect-free dry-run of a single proposed policy against recent historical actions — nothing is persisted. Use it to preview how a policy would have decided before committing it; pairs with guard() for live enforcement. Node SDK only.

Returns: Promise<{ summary: { total, matches, block, warn, require_approval, allow }, matches, sample_size, window_days }>

const sim = await claw.simulatePolicy({
  policy_type: 'risk_threshold',
  rules: { max_risk_score: 70 },
  days: 30
});
console.log(sim.summary.block, 'of', sim.summary.total, 'would block');

claw.sendMessage(params) / claw.send_message(**kwargs)

Send a point-to-point message or broadcast to all agents in the organization.

await claw.sendMessage({
  to: 'scout-agent-01',
  body: 'I have finished indexing the repository. You can start the analysis.',
  type: 'status'
});

claw.getInbox(options?) / claw.get_inbox(**kwargs)

Retrieve messages from the agent inbox with optional filtering.

Returns: Promise<{ messages, total, unread_count }>

const { messages } = await claw.getInbox({ unread: true, limit: 10 });

claw.markRead(messageIds) / claw.mark_read(message_ids)

Mark messages as read for this agent. Direct messages are marked read only for the target agent (or dashboard); broadcasts update read_by for the reading agent.

Returns: Promise<{ updated }>

const { updated } = await claw.markRead(['msg_abc123']);

claw.archiveMessages(messageIds) / claw.archive_messages(message_ids)

Archive messages for this agent so they no longer surface in the active inbox.

Returns: Promise<{ updated }>

const { updated } = await claw.archiveMessages(['msg_abc123']);

claw.createHandoff(handoff) / claw.create_handoff(**kwargs)

Create a session handoff document to persist state between agent sessions or transfer context to another agent.

await claw.createHandoff({
  summary: 'Completed initial data collection from Jira.',
  key_decisions: ['Prioritize high-severity bugs', 'Ignore closed tickets'],
  open_tasks: ['Run security scan on src/', 'Draft fix for #123'],
  next_priorities: ['Security audit']
});

claw.getLatestHandoff() / claw.get_latest_handoff()

Retrieve the most recent handoff for the current agent.

Returns: Promise<Object|null>

const handoff = await claw.getLatestHandoff();

claw.scanPromptInjection(text) / claw.scan_prompt_injection(text)

Scan untrusted input for potential prompt injection or jailbreak attempts.

Returns: Promise<{ clean: boolean, risk_level: string, recommendation: string }>

const result = await claw.scanPromptInjection(userInput);
if (!result.clean) {
  console.warn('Injection risk:', result.risk_level);
}

POST /api/pairings

Create an agent pairing request. The agent submits its public key and waits for operator approval.

Returns: { pairing: { id, status, agent_name, created_at } }

// Node SDK — pairing is on the deprecated dashclaw/legacy subpath
import { DashClaw } from 'dashclaw/legacy';
const claw = new DashClaw({ baseUrl, apiKey, agentId });

const { pairing } = await claw.createPairing(publicKeyPem, 'RSASSA-PKCS1-v1_5', 'my-agent');
console.log(pairing.id); // pair_...

GET /api/pairings

List all pairing requests for the organization. Admin API key required.

Returns: { pairings: Array<{ id, status, agent_name, created_at, approved_at }> }

const res = await fetch('/api/pairings', {
  headers: { 'x-api-key': adminApiKey }
});
const { pairings } = await res.json();

GET /api/pairings/:id

Get a specific pairing request by ID. Used by agents to poll for approval status.

Returns: { pairing: { id, status, agent_name, created_at, approved_at } }

// Node SDK (v1 legacy)
const status = await claw.getPairing(pairingId);
console.log(status.pairing.status); // pending | approved | expired

POST /api/pairings/:id/approve

Approve a pending pairing request. Admin API key required. On approval, the agent's public key is registered as a trusted identity.

Returns: { pairing: { id, status, approved_at } }

const res = await fetch(`/api/pairings/${pairingId}/approve`, {
  method: 'POST',
  headers: { 'x-api-key': adminApiKey }
});

POST /api/identities

Directly register an agent's public key as a trusted identity. Admin API key required. Bypasses the pairing flow.

Returns: { identity: { agent_id, algorithm, created_at } }

// Node SDK (v1 legacy)
await claw.registerIdentity('agent-007', publicKeyPem, 'RSASSA-PKCS1-v1_5');

GET /api/identities

List all registered agent identities for the organization. Admin API key required.

Returns: { identities: Array<{ agent_id, algorithm, created_at }> }

// Node SDK (v1 legacy)
const { identities } = await claw.getIdentities();

DELETE /api/identities/:agentId

Revoke a registered agent identity. Admin API key required. The agent's public key is removed and signature verification will fail for future actions.

Returns: { success: true }

const res = await fetch(`/api/identities/${agentId}`, {
  method: 'DELETE',
  headers: { 'x-api-key': adminApiKey }
});

GET /api/analytics

Fetch aggregated governance analytics for the organization over a rolling window. Includes action counts, guard decision totals, signal summaries, and assumption stats. Supports ?days (1–365, default 30).

Returns: { actions_total, actions_by_status, guard_decisions_total, guard_decisions_by_outcome, signals_total, assumptions_total }

const res = await fetch(`${baseUrl}/api/analytics?days=7`, {
  headers: { 'x-api-key': apiKey }
});
const data = await res.json();
// data.actions_total, data.guard_decisions_total, data.signals_total

POST /api/code-sessions/ingest-jsonl

Ingest a Claude Code JSONL transcript (or a delta). The server dedups duplicate usage fragments (Claude Code repeats one model request across many rows), computes cache-aware cost, and runs optimizer + alert detection. Accepts raw lines, a raw-gzip body (x-dashclaw-encoding: gzip header — the primary path for large transcripts), or a legacy base64 compressed_jsonl field (50 MB decompressed cap, 200k lines).

Returns: { project: { id, slug }, session: { session_uuid, inserted_messages, inserted_tool_uses, signals_inserted, alerts_inserted }, parser: { jsonl_records, model_requests, duplicate_fragments_skipped } }

// Backfill is easiest via the CLI: dashclaw code ingest
// Direct API — you supply the raw JSONL lines:
const res = await fetch(baseUrl + '/api/code-sessions/ingest-jsonl', {
  method: 'POST',
  headers: { 'x-api-key': apiKey, 'content-type': 'application/json' },
  body: JSON.stringify({
    project: { slug: 'my-repo', source_host: 'jsonl' },
    jsonl_lines: lines,        // string[] — or compressed_jsonl (base64 gzip)
  }),
});
const { session, parser } = await res.json();
// parser.duplicate_fragments_skipped = the cache-aware dedup that
// prevents the Nx cost over-count from repeated usage fragments

POST /api/code-sessions/sessions/:sessionId/optimal-files/preview

Generate the candidate file bundle for a session (read-only). Each file carries a kind, a commit recommendation, a secret-scan result, and an overwrite_risk of 'unknown' (the server can't see your working tree).

Returns: { session_id, bundle: [{ path, kind, title, content, commit_recommendation, secret_scan, overwrite_risk }], groups, analysis }

const res = await fetch(
  baseUrl + '/api/code-sessions/sessions/' + sessionId + '/optimal-files/preview',
  { method: 'POST', headers: { 'x-api-key': apiKey } }
);
const { bundle } = await res.json();   // every file already secret-redacted

POST /api/code-sessions/sessions/:sessionId/optimal-files/manifest

Persist a chosen subset of the bundle as an apply-able manifest (24 h TTL, strict path allowlist: CLAUDE.md, .claude/rules/, .claude/hooks/, .claude/skills/). Returns a ready-to-run apply command.

Returns: { manifest_id, expires_at, apply_command }

const res = await fetch(
  baseUrl + '/api/code-sessions/sessions/' + sessionId + '/optimal-files/manifest',
  {
    method: 'POST',
    headers: { 'x-api-key': apiKey, 'content-type': 'application/json' },
    body: JSON.stringify({
      selections: [{ path: 'CLAUDE.md' }, { path: '.claude/rules/testing.md' }],
    }),
  }
);
const { manifest_id, apply_command } = await res.json();
// apply_command, e.g.:  dashclaw code apply <manifest_id> --dest=. --yes

POST /api/hosted/workspaces

Mint a new trial workspace. Public, gated by DASHCLAW_HOSTED flag + Turnstile + IP rate limit. Returns the workspace ID, a one-time API key, and onboarding URL.

Returns: { workspace_id, api_key, endpoint, expires_at, trial_action_cap, key_prefix, next_steps_url }

curl -X POST https://hosted.example.com/api/hosted/workspaces \
  -H "content-type: application/json" \
  -d '{"turnstile_token": "..."}'
# → { "workspace_id": "org_...", "api_key": "oc_live_...", "endpoint": "...",
#     "expires_at": "...", "trial_action_cap": 10000, "key_prefix": "oc_live_",
#     "next_steps_url": "https://hosted.example.com/connect?hosted=org_..." }

GET /api/hosted/workspaces/:id

Admin: inspect a trial workspace. Requires an admin-role API key.

Returns: { workspace_id, status, expires_at, actions_used, trial_action_cap, created_at }

curl https://hosted.example.com/api/hosted/workspaces/org_abc \
  -H "x-api-key: <admin_key>"

DELETE /api/hosted/workspaces/:id

Admin: manually delete a trial workspace and revoke its API key.

Returns: { deleted: true, workspace_id }

curl -X DELETE https://hosted.example.com/api/hosted/workspaces/org_abc \
  -H "x-api-key: <admin_key>"

POST /api/hosted/cleanup

Cron-safe sweeper for expired trial workspaces. Accepts admin-role API key OR X-Cleanup-Secret header. Safe to run repeatedly — idempotent.

Returns: { swept: number, workspace_ids: string[] }

curl -X POST https://hosted.example.com/api/hosted/cleanup \
  -H "X-Cleanup-Secret: $HOSTED_CLEANUP_SECRET"