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 team inline — flat fan-out, a DAG plan, or a one-line flow.
  • runAgentAndWait(agentId, opts)Kick off a single employee 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 team 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).
  • rerunRun(runId, opts)Run the same work again as a NEW run, optionally with a new prompt.
  • listRunToolCalls(runId, opts)Every tool the run called — args, outcome, duration.
  • getRunSummary(runId)Plain-language summary of what the run did.
  • setRunFeedback / clearRunFeedbackRate a run; drives guidance consolidation + eval charts.
  • cancelRun(runId)Stop an in-flight run.
  • deleteRun(runId)Delete a run and its history.
  • getMetricsDashboard(opts)Org-level run metrics rollup.

Automations#

  • listWorkflows(opts)List automations — the scheduled/triggered jobs a workspace builds.
  • getWorkflow(id)One automation with its full definition (steps + trigger).
  • runWorkflow(id, opts)Run it now. Intent automations only; a paused one is refused.
  • runWorkflowAndWait(id, opts)runWorkflow + waitForRun.
  • setWorkflowEnabled(id, isEnabled)Enable or pause an automation.
  • cloneWorkflow(id)Fork into a paused copy that template upgrades never rewrite.
  • validateWorkflow(id)Static checks on a definition — gate CI on it.
  • listWorkflowSteps / getWorkflowStats / getWorkflowEvalSteps, run stats, eval pass rate.
  • listWorkflowSchedules(opts)Schedules, optionally with the next N fire times.
  • createWorkflowSchedule(opts)Put an automation on a cron (IANA timezone, not an offset).
  • updateWorkflowSchedule / deleteWorkflowScheduleEdit or remove. Pausing is isActive:false.

Employees#

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

Employee 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.

Teams & presets#

  • createSwarmPreset(input)Save a reusable team 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 — takes a plan or a flow (unknown employee, cycle, …).
  • buildSwarm(opts)Design a whole team from a description; dryRun returns the draft only.
  • runPresetBatch(presetId, opts)Run one preset over many inputs under a shared batch id.
  • getBatch(batchId) / waitForBatch(batchId, opts)Poll a batch instead of each run.

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 employee.
  • 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.
  • listApprovalQueue() / bulkDecideApprovals(opts)Everything waiting on a human; decide many at once.
  • getCapabilities()What this workspace's plan and config actually allow.
  • getPostureDrift() / getGovernanceFleet()Drift from catalog definitions; governance across every employee.
  • listApiKeys / createApiKey / rotateApiKey / revokeApiKeyKey lifecycle. The secret is returned once.
  • listMembers(opts)Who is in the workspace.
  • getMe()Verify the key; read org + scope.

Quality: evals & guidance#

  • getEvalSummary(opts)Org-wide eval pass rate over a rolling window.
  • getEvalRegressions(opts)Cases that used to pass and now fail — the CI-gate signal.
  • getEvalTimeseries(opts)Pass rate over time, for charting.
  • getAgentGuidance(id) / setAgentGuidance(id, text)The standing guidance appended to an employee's instructions.
  • consolidateAgentGuidance(id, opts)Re-derive guidance from recent run feedback.
  • getFeedbackSummary / getFeedbackTimeseriesThumbs up/down across the workspace.
  • listRecentNotes(opts)Notes people left on runs, employees and automations.

Usage, cost & limits#

  • getUsage(report, opts)One usage/cost report — cost, cost/timeseries, cost-by-agent, peak-hours, tools, …
  • getOrgBudget() / setOrgBudget(change)Monthly spend cap, and whether it holds runs or only reports.
  • getOrgQuotas() / setOrgQuotas(overrides)Plan quotas and consumption.
  • getRateLimit() / setRateLimit(limits)Runs-per-hour and tokens-per-day caps.
  • listStorage(opts) / getStorageUsage()Files runs have written, and the space they take.
  • listEvents(opts) / getEventsSummary(opts)Employee events across every run — the org-wide twin of listRunEvents.

Catalog & packs#

  • listCatalogAgents() / installCatalogAgent(key)Ready-made employees; install copies the definition in as yours.
  • listCatalogSwarmPresets() / installCatalogSwarmPreset(key)Ready-made teams (prerequisite employees install with them).
  • listCatalogMcpServers() / installCatalogMcpServer(key)Ready-made MCP server configs.
  • listOperationsTemplates() / installOperationsTemplate(key)Ready-made operations workflows.
  • listPacks() / importPack(pack) / installPack(key, opts)Multi-item packs. An install never loosens governance unsaid.
  • listIntegrations()Connected integrations.
  • listMessengerLinks / linkMessengerPage / unlinkMessengerPageBind a Messenger page to an employee.
  • listAnnouncements() / dismissAnnouncement(id)Platform announcements.

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