From zero to a working call in five minutes.

This guide walks the shortest path from a fresh workspace to an authenticated round-trip against the production API. Every step below is reproducible — keep this page open in a second tab and copy as you go.

Prerequisites

• A Link AI workspace — sign up at linkaiil.com/get-started if you do not have one.
• Node.js 20 or newer (or any HTTP client — examples below also show curl).
• Roughly five minutes.

Step 1. Mint an API key

Open Settings → Developers inside your workspace and click Create token. Give it a memorable label — “billing-export prod” reads better in an incident review than “token-3”. Copy the value immediately. Link AI stores only a hashed prefix, so the plaintext is shown exactly once.

Tokens are prefixed with lnk_live_ in production and lnk_test_ in staging. Treat them as bearer secrets — no committing to git, no client bundles, no Slack DMs.

Step 2. Confirm the credential

Before wiring anything that creates a side effect, prove the token resolves to the right workspace. The /v1/whoami endpoint is a cheap, idempotent ping that returns the workspace id and the plan tier.

curl https://api.linkaiil.com/v1/whoami \
  -H "Authorization: Bearer $LINKAI_TOKEN"

{
  "workspace_id": "ws_2b9c1f3a",
  "workspace_name": "Acme Health",
  "plan": "growth",
  "permissions": ["voice:write", "mailer:write", "webhooks:write"]
}

Step 3. Place your first call

Voice is the most common “hello world”. Pick an agent you already configured in the dashboard, supply the destination number in E.164, and the platform handles the carrier handoff.

import { LinkAI } from "@linkai/sdk";

const linkai = new LinkAI({ apiKey: process.env.LINKAI_TOKEN! });

const call = await linkai.voice.calls.create({
  agentId: "agt_5fd1a02b",
  to: "+972541234567",
  // Free-form payload echoed back in every webhook for this call.
  metadata: { lead_id: "lead_9182" },
});

console.log(call.id, call.status);

The response returns immediately with a call_idand an initial queued status. The real outcome (answered, voicemail, no-answer, transcript) arrives on the webhook stream — see Webhooks.

curl equivalent

curl https://api.linkaiil.com/v1/voice/calls \
  -H "Authorization: Bearer $LINKAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_5fd1a02b",
    "to": "+972541234567",
    "metadata": { "lead_id": "lead_9182" }
  }'

Step 4. Wire a webhook

Add a webhook URL in the same Settings → Developerspanel. Link AI signs every delivery with HMAC-SHA256 over the raw request body. Verify the signature before parsing the JSON.

import crypto from "node:crypto";
import express from "express";

const app = express();

// Raw body — DO NOT use express.json() before this handler.
app.post(
  "/linkai/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.header("X-Linkai-Signature") ?? "";
    const expected = crypto
      .createHmac("sha256", process.env.LINKAI_WEBHOOK_SECRET!)
      .update(req.body)
      .digest("hex");

    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
      return res.status(401).end();
    }

    const event = JSON.parse(req.body.toString("utf8"));
    // event.type === "voice.call.completed" | "mailer.reply.received" | ...
    res.status(204).end();
  },
);

Where to next

• Authentication — token rotation, scopes, and the browser-side Clerk pattern.
• REST API — endpoint catalog for voice, mailer, and shared workspace primitives.
• Webhooks — full event types table, retry semantics, and replay protection.