Skip to content

API Reference

DarhimLabs API v2.4.0

Stable OpenAPI reference powered by `specs/openapi.json`, sandbox bearer auth metadata and generated artifacts.

InboxBotsAgentsLeadsKnowledgeVoiceWebhooksWorkspacesCompliance126 operations
JSON specYAML specPostmanPublic workspaceInsomniaBrunoIntegrationsCustom webhooksWebhook Playground

First request in 5 minutes

Public API docs, sandbox snippets and downloadable specs in one place.

Start with a sandbox API key, keep production secrets out of browser demos, then jump into operation pages when you need exact request and response contracts.

Do not paste a production secret into public demos. The embedded try-it-out flow is configured for sandbox usage and should use `dl_test_...` or generated sandbox keys only.
Open Developer Console Webhook Playground

126

Operations

9

Tags

API key + OAuth

Auth

Authentication

Use `Authorization: Bearer <api_key>` for server-to-server calls or OAuth authorization code flow for partner apps.

Scopes

Every API key and OAuth app is constrained by explicit scopes. Write operations require write scopes.

Pagination

List endpoints use cursor pagination. Keep the next cursor and avoid page-number polling.

Idempotency

Send `Idempotency-Key` on POST/PATCH requests that create messages, leads, runs or webhook replays.

Errors

Every error response includes a safe message and request id. Use `X-Request-ID` when debugging with support.

Rate limits

Respect `429` and `Retry-After`. Use exponential backoff with jitter for bursty workloads.

Downloadable artifacts

OpenAPI, Postman, Insomnia and Bruno exports.

Copy canonical URL
OpenAPI JSONCanonical specOpenAPI YAMLCI-friendlyPostmanCollection importInsomniaWorkspace importBrunoLocal collection

API scopes

bots:readbots:writewebhooks:readwebhooks:writemessages:writeleads:readleads:writeconversations:readusage:readevents:readapi_logs:readoauth:readoauth:writesandbox:readsandbox:writeopenapi:readsdk:writeterraform:read
Node / TypeScript
npm install @darhimlabs/node
export DARHIMLABS_API_KEY=dl_test_...
Python
pip install darhimlabs
export DARHIMLABS_API_KEY=dl_test_...
PHP
composer require darhimlabs/php-sdk
export DARHIMLABS_API_KEY=dl_test_...
CLI
npm install -g @darhimlabs/cli
dl login
dl api logs

Wybierz jezyk

1

Wygeneruj API key

Wejdz do Developer Console, utworz klucz testowy `dl_test_...` i zapisz go w secret managerze. Klucz produkcyjny `dl_live_...` pokazujemy tylko raz.

bash
DARHIMLABS_API_KEY=dl_test_...
2

Zainstaluj SDK dla Node.js

Oficjalne SDK sa projektowane jako cienka, typed warstwa nad OpenAPI v2.

node
npm install @darhimlabs/node
3

Wykonaj pierwszy call

Pobierz otwarte konwersacje z sandbox workspace. Ten krok powinien zamknac time-to-first-API-call w kilku minutach.

node
import { DarhimLabs } from "@darhimlabs/node";

const client = new DarhimLabs(process.env.DARHIMLABS_API_KEY!);
const conversations = await client.inbox.conversations.list({
  status: "open",
  limit: 10
});

console.log(`Found ${conversations.data.length} open conversations`);

Sandbox wykonuje tylko whitelisted snippet `quickstart-step-3`.

4

Wyslij wiadomosc

Kazdy write request dostaje `Idempotency-Key`, zeby retry nie zdublowal wiadomosci.

node
const conversation = conversations.data[0];

const message = await client.inbox.conversations.sendMessage(conversation.id, {
  channel: conversation.channel,
  content: "Czesc! Czym moge pomoc?"
}, {
  idempotencyKey: "msg_quickstart_001"
});

console.log("Sent:", message.id);

Sandbox wykonuje tylko whitelisted snippet `quickstart-step-4`.

5

Subscribe webhooks

Webhook secret zapisz od razu. Do weryfikacji podpisu uzywaj raw body i timing-safe comparison.

node
const endpoint = await client.webhooks.endpoints.create({
  url: "https://your-app.com/webhooks/darhimlabs",
  events: ["conversation.created", "message.received"],
  secret: "auto"
});

console.log("Webhook secret:", endpoint.secret);

Sandbox wykonuje tylko whitelisted snippet `quickstart-step-5`.

Co dalej?

Po pierwszym callu najczesciej developerzy dodaja webhooks, tworza leady z konwersacji i podpina webhook signature verification.

Webhook signatureCreate leadAgents API

Kalkulator limitow

Czy obecny plan obsluzy twoj ruch?

Liczymy bezpieczna pojemnosc na 80% limitu, bo produkcyjny ruch zawsze ma peaki, retry i kolejki.

120 req/min

180 req/min peak

35 000 req/day

Dla `429` uzyj `Retry-After`, exponential backoff z jitterem i `Idempotency-Key` przy mutacjach. To zabezpiecza przed duplikacja wiadomosci, leadow i webhook replay.

cURL to SDK

Zamien cURL na wywolanie oficjalnego SDK

listConversationsInboxGETconfidence: high
await client.inbox.conversations.list({ status: "open", limit: "10" });

Webhook signing

Verify signatures against the raw request body with timing-safe comparison.

Use replay protection and idempotency keys for every delivery handler.

Test locally with Webhook Playground.

Operation reference

The reference below is rendered from the canonical OpenAPI contract and links each operation to a dedicated guide.

OpenAPI reference

All API operations

Server-rendered operation index with methods, paths, scopes and schema downloads. It remains available even when the interactive client reference cannot be loaded by the browser.

JSONYAML
DarhimLabs API operations with HTTP method, path, required scopes and operation page links.
MethodPathOperationScopesGuide
GET/

API root

getApiRoot

read
Open
GET/inbox/conversations

List conversations

listConversations

conversations:read
Open
POST/inbox/conversations

Create conversation

createConversation

messages:write
Open
GET/inbox/conversations/{id}

Get conversation details

getConversation

conversations:read
Open
PATCH/inbox/conversations/{id}

Update conversation

updateConversation

messages:write
Open
GET/inbox/conversations/{id}/messages

List messages

listMessages

conversations:read
Open
POST/inbox/conversations/{id}/messages

Send message

sendMessage

messages:write
Open
POST/inbox/conversations/{id}/ai-draft

Generate AI Draft

createAiDraft

messages:write
Open
POST/inbox/conversations/{id}/assign

Assign conversation

assignConversation

messages:write
Open
POST/inbox/conversations/{id}/resolve

Resolve conversation

resolveConversation

messages:write
Open
GET/inbox/templates

List reply templates

listReplyTemplates

conversations:read
Open
POST/inbox/templates

Create reply template

createReplyTemplate

messages:write
Open
GET/inbox/tags

List inbox tags

listInboxTags

conversations:read
Open
POST/inbox/tags

Create inbox tag

createInboxTag

messages:write
Open
GET/conversations

List conversations public API v2

listPublicConversations

conversations:read
Open
GET/bots

List bots

listBots

bots:read
Open
POST/bots

Create bot

createBot

bots:write
Open
GET/bots/{id}

Get bot details

getBot

bots:read
Open
PATCH/bots/{id}

Update bot

updateBot

bots:write
Open
DELETE/bots/{id}

Delete bot

deleteBot

bots:write
Open
POST/bots/{id}/publish

Publish bot

publishBot

bots:write
Open
GET/bots/{id}/versions

List bot versions

listBotVersions

bots:read
Open
POST/bots/{id}/versions

Create bot version

createBotVersion

bots:write
Open
POST/bots/{id}/versions/{run_id}/rollback

Rollback bot version

rollbackBotVersion

bots:write
Open
POST/bots/{id}/clone

Clone bot

cloneBot

bots:write
Open
GET/bots/{id}/tools

List bot tools

listBotTools

bots:read
Open
POST/bots/{id}/tools

Attach bot tool

attachBotTool

bots:write
Open
GET/bots/{id}/guardrails

Get bot guardrails

getBotGuardrails

bots:read
Open
PATCH/bots/{id}/guardrails

Update bot guardrails

updateBotGuardrails

bots:write
Open
POST/bots/{id}/messages

Send message to bot

sendBotMessage

bots:write
Open
GET/agents

List agents

listAgents

read
Open
POST/agents

Create agent

createAgent

write
Open
GET/agents/{id}

Get agent details

getAgent

read
Open
PATCH/agents/{id}

Update agent

updateAgent

write
Open
GET/agents/{id}/runs

List agent runs

listAgentRuns

read
Open
POST/agents/{id}/runs

Create agent run

createAgentRun

write
Open
GET/agents/{id}/runs/{run_id}

Get agent run details

getAgentRun

read
Open
POST/agents/{id}/runs/{run_id}/approve

Approve agent run

approveAgentRun

write
Open
POST/agents/{id}/runs/{run_id}/cancel

Cancel agent run

cancelAgentRun

write
Open
POST/agents/{id}/dry-run

Agent dry-run

dryRunAgent

write
Open
POST/agents/{id}/dry-run/stream

Stream agent dry-run

streamAgentDryRun

write
Open
GET/agents/{id}/approvals

List agent approvals

listAgentApprovals

read
Open
GET/leads

List leads

listLeads

leads:read
Open
POST/leads

Create lead

createLead

leads:write
Open
GET/leads/{id}

Get lead details

getLead

leads:read
Open
PATCH/leads/{id}

Update lead

updateLead

leads:write
Open
DELETE/leads/{id}

Delete lead

deleteLead

leads:write
Open
POST/leads/{id}/qualify

Qualify lead

qualifyLead

leads:write
Open
POST/leads/{id}/sync

Sync lead to CRM

syncLeadToCrm

leads:write
Open
GET/leads/{id}/activities

List lead activities

listLeadActivities

leads:read
Open
POST/leads/{id}/activities

Create lead activity

createLeadActivity

leads:write
Open
POST/leads/{id}/status

Update lead status

updateLeadStatus

leads:write
Open
GET/knowledge/bases

List knowledge bases

listKnowledgeBases

read
Open
POST/knowledge/bases

Create knowledge base

createKnowledgeBase

write
Open
GET/knowledge/bases/{id}

Get knowledge base details

getKnowledgeBase

read
Open
PATCH/knowledge/bases/{id}

Update knowledge base

updateKnowledgeBase

write
Open
DELETE/knowledge/bases/{id}

Delete knowledge base

deleteKnowledgeBase

write
Open
GET/knowledge/bases/{id}/documents

List documents

listKnowledgeDocuments

read
Open
POST/knowledge/bases/{id}/documents

Upload document

uploadKnowledgeDocument

write
Open
GET/knowledge/documents/{id}

Get document details

getKnowledgeDocument

read
Open
DELETE/knowledge/documents/{id}

Delete document

deleteKnowledgeDocument

write
Open
POST/knowledge/search

RAG search

searchKnowledge

write
Open
POST/knowledge/crawl

Start website crawl

crawlKnowledgeSource

write
Open
GET/knowledge/gaps

List knowledge gaps

listKnowledgeGaps

read
Open
GET/voice/numbers

List voice numbers

listVoiceNumbers

read
Open
POST/voice/numbers

Provision voice number

provisionVoiceNumber

write
Open
GET/voice/calls

List voice calls

listVoiceCalls

read
Open
POST/voice/calls

Start voice call

createVoiceCall

write
Open
GET/voice/calls/{id}

Get voice call details

getVoiceCall

read
Open
POST/voice/calls/{id}/transfer

Transfer voice call to human

transferVoiceCall

write
Open
GET/voice/calls/{id}/recording

Get recording

getVoiceRecording

read
Open
GET/voice/calls/{id}/transcript

Get transcript

getVoiceTranscript

read
Open
POST/voice/token

Create voice client token

createVoiceToken

write
Open
GET/webhooks/endpoints

List webhook endpoints

listWebhookEndpoints

webhooks:read
Open
POST/webhooks/endpoints

Create webhook endpoint

createWebhookEndpoint

webhooks:write
Open
GET/webhooks/endpoints/{id}

Get webhook endpoint details

getWebhookEndpoint

webhooks:read
Open
PATCH/webhooks/endpoints/{id}

Update webhook endpoint

updateWebhookEndpoint

webhooks:write
Open
DELETE/webhooks/endpoints/{id}

Delete webhook endpoint

deleteWebhookEndpoint

webhooks:write
Open
POST/webhooks/endpoints/{id}/test

Send test webhook

testWebhookEndpoint

webhooks:write
Open
POST/webhooks/endpoints/{id}/rotate-secret

Rotate webhook secret

rotateWebhookSecret

webhooks:write
Open
GET/webhooks/deliveries

List webhook deliveries

listWebhookDeliveries

webhooks:read
Open
GET/webhooks/deliveries/{id}

Get webhook delivery details

getWebhookDelivery

webhooks:read
Open
POST/webhooks/deliveries/{id}/replay

Replay webhook delivery

replayWebhookDelivery

webhooks:write
Open
GET/webhooks/events

Event catalog

listWebhookEvents

webhooks:read
Open
GET/webhooks/playground/{token}

Capture GET in Webhook Playground

captureWebhookPlaygroundGet

webhooks:read
Open
POST/webhooks/playground/{token}

Capture POST in Webhook Playground

captureWebhookPlaygroundPost

webhooks:write
Open
PUT/webhooks/playground/{token}

Capture PUT in Webhook Playground

captureWebhookPlaygroundPut

webhooks:write
Open
PATCH/webhooks/playground/{token}

Capture PATCH in Webhook Playground

captureWebhookPlaygroundPatch

webhooks:write
Open
DELETE/webhooks/playground/{token}

Capture DELETE in Webhook Playground

captureWebhookPlaygroundDelete

webhooks:write
Open
GET/events

Public event catalog

listEventCatalog

webhooks:read
Open
GET/webhook-endpoints

List webhook endpoints public API v2

listPublicWebhookEndpoints

webhooks:read
Open
POST/webhook-endpoints

Create webhook endpoint public API v2

createPublicWebhookEndpoint

webhooks:write
Open
GET/webhook-endpoints/{id}

Get webhook endpoint details public API v2

getPublicWebhookEndpoint

webhooks:read
Open
PATCH/webhook-endpoints/{id}

Update webhook endpoint public API v2

updatePublicWebhookEndpoint

webhooks:write
Open
DELETE/webhook-endpoints/{id}

Delete webhook endpoint public API v2

deletePublicWebhookEndpoint

webhooks:write
Open
GET/workspaces/current

Get current workspace

getCurrentWorkspace

read
Open
GET/workspaces/{id}

Get workspace details

getWorkspace

read
Open
PATCH/workspaces/{id}

Update workspace

updateWorkspace

write
Open
GET/workspaces/{id}/members

List workspace members

listWorkspaceMembers

read
Open
POST/workspaces/{id}/members

Invite workspace member

inviteWorkspaceMember

write
Open
PATCH/workspaces/{id}/members/{member_id}

Update member role

updateWorkspaceMember

write
Open
DELETE/workspaces/{id}/members/{member_id}

Remove workspace member

removeWorkspaceMember

write
Open
GET/workspaces/{id}/usage

Usage workspace

getWorkspaceUsage

read
Open
GET/usage

Usage public API v2

getPublicApiUsage

read
Open
GET/api-logs

Live API logs

listApiLogs

read
Open
GET/oauth/apps

List OAuth apps

listOAuthApps

read
Open
POST/oauth/apps

Create OAuth app

createOAuthApp

write
Open
PATCH/oauth/apps

Update OAuth app

updateOAuthApp

write
Open
GET/openapi-snapshots

List OpenAPI snapshots

listOpenApiSnapshots

read
Open
POST/openapi-snapshots

Create OpenAPI snapshot

createOpenApiSnapshot

write
Open
GET/sandbox-workspaces

List sandbox workspaces

listSandboxWorkspaces

read
Open
POST/sandbox-workspaces

Create sandbox workspace

createSandboxWorkspace

write
Open
GET/sdk-generations

List SDK generations

listSdkGenerations

read
Open
POST/sdk-generations

Start SDK generation

createSdkGeneration

write
Open
GET/terraform-resources

List Terraform resources

listTerraformResources

read
Open
GET/compliance/audit-log

Audit log

listAuditLog

read
Open
GET/compliance/dsar

List DSAR requests

listDsarRequests

read
Open
POST/compliance/dsar

Create DSAR request

createDsarRequest

write
Open
GET/compliance/dsar/{id}

Get DSAR request details

getDsarRequest

read
Open
POST/compliance/dsar/{id}/export

Export DSAR request

exportDsarRequest

write
Open
GET/compliance/evidence

List compliance evidence

listComplianceEvidence

read
Open
GET/compliance/evidence/{id}/download

Download compliance evidence

downloadComplianceEvidence

read
Open
POST/compliance/pii-redaction

Redact PII

redactPii

write
Open
GET/compliance/retention

Retention policies

getRetentionPolicies

read
Open
PATCH/compliance/retention

Update retention policies

updateRetentionPolicies

write
Open
GET/health

Health API

getApiHealth

read
Open