Bahini
Open app

Reference

API reference

Every method on the BahiniClient, grouped. Each maps to one /api/v1 endpoint. Full parameter and return types ship with the package's TypeScript definitions.

The SDK is fully typed — hover any method in your editor for the exact argument and return shapes. This page is the map; the types are the territory.

Runs#

  • runAgent(agentId, opts)Kick off a one-shot single-agent run. Returns { runId }.
  • runPreset(presetId, opts)Run a saved swarm/coordinator preset.
  • runSwarm(opts)Run a swarm inline — flat fan-out or a DAG plan.
  • runAgentAndWait(agentId, opts)Kick off a single agent and wait for the result.
  • waitForRun(runId, opts)Poll until terminal or waiting-for-approval.
  • watchRun(runId, opts)Stream live events via onEvent; resolves with final detail.
  • getRun(runId)Status, output, steps, approvals.
  • getRunTranscript(runId)Chronological event transcript.
  • getRunDag(runId)Live swarm DAG with per-node status (or null).
  • getRunEval(runId)Golden-suite eval verdict — the CI gate.
  • getRunCost(runId)USD cost + token usage for the run.
  • listRuns(opts)List runs newest-first; filter by status/agent/preset/metadata.
  • listRunEvents(runId, opts)Page a run's events (basis for watchRun).
  • cancelRun(runId)Stop an in-flight run.
  • deleteRun(runId)Delete a run and its history.
  • getMetricsDashboard(opts)Org-level run metrics rollup.

Agents#

  • createAgent(input)Provision an agent. Returns { id, key, name }.
  • updateAgent(agentId, patch)Edit fields; status ARCHIVED/PAUSED/ACTIVE.
  • listAgents(opts)List the org's agents.
  • listModelProfiles(opts)Discover modelProfileId + failover chains.
  • listTools()The built-in tool catalog (keys + JSON-schema params).

Agent config (as code)#

  • getAgentConfig(agentId)Whole config snapshot in one call.
  • applyAgentConfig(agentId, config)Apply desired config; best-effort per surface.
  • setAgentTools(agentId, keys)Set-equality tool grant. Returns the diff.
  • grantAgentTool / revokeAgentToolAdditive/idempotent single-key grant + revoke.
  • grantAgentToolsFromMcp(agentId, serverId)Grant every tool an MCP server exposes.
  • setAgentCapabilityScope(agentId, scope)Allowed HTTP domains, denied tools, storage prefixes.
  • setAgentApprovalPolicy(agentId, policy)Approval-gate specific tools.
  • setAgentBudget(agentId, budget)Hard ceilings: iterations/tokens/duration/errors.
  • setAgentGuardrails(agentId, guardrails)PII/secrets/injection guards; enforce or monitor.
  • setAgentResponseFormat(agentId, rf)Structured output: json_object / json_schema.
  • setAgentGoldenSuite(agentId, cases)Define the eval quality bar as data.
  • getAgent* (tools, capabilityScope, …)Read side of each setAgent* surface.

Swarms & presets#

  • createSwarmPreset(input)Save a reusable swarm shape.
  • updateSwarmPreset / deleteSwarmPresetEdit or remove a preset.
  • listPresets() / getPreset(id)List / read presets.
  • setPresetGuardrails(presetId, guardrails)Persist a preset's guardrail policy.
  • validateSwarmPlan(opts)Pre-flight a DAG plan (unknown agent, cycle, …).

Tools & MCP#

  • createCustomTool(input)Register a named, schema'd HTTP tool ({{arg}} / {{secret:NAME}}).
  • setCustomTool(key, patch)Enable/disable (kill switch) or edit a custom tool.
  • listCustomTools() / deleteCustomTool(key)List / remove custom tools.
  • createMcpServer(input)Register an MCP server (command policy applies).
  • discoverMcpServerTools(id)Refresh an MCP server's tool list.
  • setMcpServer(id, patch)Enable/disable an MCP server.
  • listMcpServers(opts)List MCP servers (paginated).

Connectors & credentials#

  • createConnector(input)Provision a read-only Postgres connector.
  • listConnectors() / deleteConnector(name)List / remove connectors (coordinates only).
  • setCredential(input)Store a secret in the org credential vault.
  • grantCredentialToAgent(...)Grant a vault secret to an agent.
  • listCredentials() / deleteCredential(...)List / remove vault secrets.

Dashboards & datasets#

  • publishDataset(input)Push rows into a named dataset.
  • publishDatasetFromCsv(dataset, csv, opts)Parse a CSV client-side and publish.
  • listDatasets() / getDataset(key) / deleteDataset(key)Manage datasets.
  • upsertDashboard(input)Define a dashboard as code (by title).
  • updateDashboard / getDashboard / deleteDashboard / listDashboardsManage boards.
  • createAlert(input)Threshold/change/stale metric alert on a dataset.
  • updateAlert / listAlerts / deleteAlertManage metric alerts.

Governance & webhooks#

  • decideApproval(approvalId, opts)Approve/reject a gated run from code.
  • getOrgEgress() / setOrgEgress(...)Read/set org network egress policy.
  • getOrgGuardrails() / setOrgGuardrails(...)Org-wide guardrail defaults.
  • previewGuardrails(...) / getGuardrailActivity(...)Dry-run + read guardrail activity.
  • listAuditLog(opts)Read the hash-chained audit log.
  • createWebhook / listWebhooks / deleteWebhookOutbound run-completion webhooks (HMAC-signed).
  • getWebhookDeliveries(...)Inspect webhook delivery attempts.
  • listSecurityEventTypes()The security event catalog for SIEM subscriptions.
  • getMe()Verify the key; read org + scope.

Types#

Core exported types you'll touch:

 
ts
import {
  BahiniClient,
  BahiniApiError,
  parseRunOutput,
  isTerminal,
  type RunStatus,
  type RunDetail,
  type RunStep,
  type DashboardWidget,
} from "@bahini/sdk";
PreviousDashboards & data