Developer Reference

WEBEE API Reference

The WEBEE REST API gives you programmatic access to agents, contacts, calls, bookings, campaigns, analytics, and billing — all workspace-scoped and secured by API key.

22 endpoints
across 8 resource types
Bearer auth
per-workspace API keys
60 req / min
per key, with Retry-After
Base URL
https://app.webespokeai.com/api/v1

Authentication

All requests require a WEBEE API key issued from Settings → Developer API. Keys are workspace-scoped.

Pass your key in the Authorization header on every request:

Authorization: Bearer wbee_xxxxxxxxxxxxxxxxxxxxxxxx
Security: Never expose API keys in client-side code or public repositories. Keys can be rotated or revoked from the Developer API settings at any time.
Quick start — list your agents
curl "https://app.webespokeai.com/api/v1/agents" \
  -H "Authorization: Bearer wbee_your_key_here"

Agents

List, deploy, test, and archive your WEBEE AI agents.

Leads

Create and list leads in your CRM pipeline.

Contacts

Full CRUD for contacts — search, create, and update with pipeline stage tracking.

Calls

Trigger outbound calls, list call logs, and pull detailed analytics.

Call Status Values
initiatedCall created and being dialled out.
in_progressAgent and caller are connected.
completedCall ended normally. Summary and transcript are available.
endedAlias for completed (used by some voice providers).
no_answerDestination did not pick up.
busyDestination line was busy.
cancelledCall was cancelled before it connected.
failedProvider-level failure (bad number, network error, etc.).
errorInternal system error during call setup.
Sentiment Values
positiveAgent determined the caller was happy, interested, or engaged.
neutralNo strong positive or negative signal detected.
negativeCaller expressed frustration, disinterest, or complaints.
Post-call Summary Fields
summarystring | nullAI-generated narrative summary of the call.
transcriptstring | nullFull verbatim transcript (agent + caller turns).
recording_urlstring | nullSigned URL to the call recording audio file.
sentimentstring | nullDetected caller sentiment: positive | neutral | negative.
call_outcomestring | nullOutcome label set by the agent flow (e.g. booked, callback_requested).
disconnection_reasonstring | nullWhy the call ended (e.g. agent_hangup, user_hangup, dial_failed).
duration_secondsnumber | nullTotal talk time in seconds.
cost_usdnumber | nullProvider cost for this call in USD.

Bookings

Create and manage calendar bookings captured by your agents.

Campaigns

Enrol contacts into outbound campaigns and monitor performance metrics.

Analytics

High-level workspace metrics and AI-driven growth recommendations.

Billing & Costs

Access billing plan details, provider cost breakdowns, call profitability, and usage metrics.

Knowledge

Upload documents and text to power your agent's knowledge base.

Webhooks

Subscribe to real-time events. All payloads are signed with HMAC-SHA256.

Available Event Types
lead.createdlead.updatedcall.startedcall.completedcall.failedbooking.createdbooking.updatedbooking.cancelledcampaign.completeddocument.uploadedagent.deployed
Webhook payload shape
{
  "event": "lead.created",
  "workspace_id": "wsp_xxxxxxxxxxxx",
  "timestamp": "2026-06-17T10:00:00.000Z",
  "data": { /* resource object */ }
}
Verifying the signature (Node.js)
import crypto from "node:crypto";

function verifyWebeeWebhook(rawBody, signature, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

// Express
app.post("/webhooks/webee", express.raw({ type: "*/*" }), (req, res) => {
  const sig    = req.headers["x-webee-signature"];
  const secret = process.env.WEBEE_WEBHOOK_SECRET;
  if (!verifyWebeeWebhook(req.body.toString(), sig, secret))
    return res.status(403).send("Invalid signature");
  const event = JSON.parse(req.body.toString());
  // handle event.event ...
  res.sendStatus(200);
});

Errors

WEBEE uses standard HTTP status codes. All error responses follow the same JSON shape.

Error response shape
{
  "error": "Agent not found",
  "status": 404
}
400Bad RequestMissing or invalid parameters.
401UnauthorizedInvalid or missing API key.
403ForbiddenYour key lacks the required permission scope.
404Not FoundThe requested resource does not exist in your workspace.
422UnprocessableRequest is valid but cannot be completed (e.g. agent not deployed).
429Too Many RequestsRate limit exceeded. Check the Retry-After header.
500Server ErrorSomething went wrong on our end. Contact support.

Ready to integrate?

Generate your first API key from the Developer API settings inside your workspace.

Get your API key