Migration guide: v1 to v2

API v2 rozdziela monolityczne endpointy v1 na czytelne moduly: Inbox, Bots, Agents, Leads, Knowledge, Voice, Webhooks i Compliance. Migracja zwykle zajmuje 1-2 dni, jesli uzywasz tylko wysylki wiadomosci i webhookow.

Breaking changes

| v1 | v2 | Co sie zmienilo | | --- | --- | --- | | POST /api/v1/chat | POST /inbox/conversations/{id}/messages | Wiadomosci sa przypiete do konwersacji i maja idempotency. | | GET /api/v1/chats | GET /inbox/conversations | Cursor pagination zamiast offset. | | POST /api/v1/bot/run | POST /agents/{id}/runs | Run agenta jest osobnym zasobem z approval i cancel. | | X-DL-Signature | DL-Status-Signature | Podpis webhooka uzywa formatu t=timestamp,v1=hex. |

Pagination

Before:

curl "https://api.darhimlabs.pl/api/v1/chats?offset=100&limit=50"

After:

curl "https://api.darhimlabs.pl/api/v2/inbox/conversations?cursor=$CURSOR&limit=50" \
  -H "Authorization: Bearer $DARHIMLABS_API_KEY"

Node.js diff

// v1
await fetch("https://api.darhimlabs.pl/api/v1/chat", {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify({ message: "Czesc" })
});

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

const client = new DarhimLabs(process.env.DARHIMLABS_API_KEY!);
await client.inbox.conversations.sendMessage("conv_123", {
  content: "Czesc"
}, {
  idempotencyKey: "message_123"
});

Python diff

# v1
requests.post("/api/v1/chat", json={"message": "Czesc"})

# v2
from darhimlabs import DarhimLabs

client = DarhimLabs(api_key=os.environ["DARHIMLABS_API_KEY"])
client.inbox.conversations.send_message(
    conversation_id="conv_123",
    content="Czesc",
    idempotency_key="message_123"
)

PHP diff

// v1
$http->post("/api/v1/chat", ["message" => "Czesc"]);

// v2
$client = new DarhimLabs\Client(["api_key" => $_ENV["DARHIMLABS_API_KEY"]]);
$client->inbox->conversations->sendMessage(
    "conv_123",
    ["content" => "Czesc"],
    ["idempotency_key" => "message_123"]
);

Ruby diff

# v1
Faraday.post("/api/v1/chat", { message: "Czesc" }.to_json)

# v2
client = DarhimLabs::Client.new(api_key: ENV["DARHIMLABS_API_KEY"])
client.inbox.conversations.send_message(
  "conv_123",
  content: "Czesc",
  idempotency_key: "message_123"
)

Checklist

1. Wygeneruj nowy dl_test_... key w /dashboard/deweloperzy.
2. Zamien offset pagination na cursor pagination.
3. Dodaj Idempotency-Key dla kazdego POST i PATCH.
4. Zmien webhook signature header na DL-Status-Signature.
5. Przetestuj requesty w sandboxie i Webhook Playground.