Developers

The Tellane API.

One REST surface — the same one the dashboard runs on — plus signed webhooks for what happens in your lanes and an MCP server for assistants. Base URL https://api.tellane.com.

Authentication

Create a key under Settings → API keys and send it as a bearer token. A live key (tl_live_…) can read and edit lanes, stops, screens, and leads — the routes marked LIVE KEY below. A test key (tl_test_…) can only read. Keys belong to one workspace and can never touch the team, billing, integrations, or other keys.

curl https://api.tellane.com/w/{workspace}/lanes \
  -H "Authorization: Bearer tl_live_…"

{workspace} is your workspace slug — the subdomain of your public address. Errors are JSON: { "error": "…", "code": "…" } with the usual status (400 invalid, 401 no or bad key, 403 not allowed for this key, 404, 409 conflict, 429).

Rate limits

600 requests per minute per key. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (unix seconds); past the limit you get a 429 with Retry-After.

Public routes

No key needed — these are what the player itself calls, useful if you embed lanes your own way.

Webhooks

Register https endpoints under Settings → Webhooks. Each event is one JSON POST: { "id", "event", "createdAt", "attempt", "data" }, retried five times on a 1 m → 5 m → 30 m → 2 h → 12 h backoff until your endpoint answers 2xx within 10 seconds. The delivery log in Settings shows every attempt.

Headers: X-Tellane-Event, X-Tellane-Delivery, X-Tellane-Timestamp, and X-Tellane-Signature: t=<unix>,v1=<hex> — an HMAC-SHA256 over <t>.<raw body> with the endpoint's secret. Verify it before trusting a delivery:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret, header, rawBody, maxAgeSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > maxAgeSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "hex"), b = Buffer.from(parts.v1 ?? "", "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

MCP

POST https://api.tellane.com/mcp speaks the Model Context Protocol (Streamable HTTP, stateless) and authenticates with an API key — a test key is enough, every tool is read-only: workspace_info, list_lanes, get_lane, analytics_summary, list_leads. Claude Desktop, Claude Code, Cursor, ChatGPT, and Copilot all take this shape:

{
  "mcpServers": {
    "tellane": {
      "url": "https://api.tellane.com/mcp",
      "headers": {
        "Authorization": "Bearer tl_test_YOUR_KEY"
      }
    }
  }
}

Questions, or a route you need that isn't here? [email protected]