Documentation

The Pegasus API is REST over HTTPS with JSON in both directions. The same key opens both the REST API and the MCP server — there are not two credentials to manage.

1. Sign in to the console and open Desarrolladores → Llaves.
2. Create a key. Choose the test environment while you build: a test key can never make a telephone ring.
3. Check only the scopes your integration needs. There are no wildcards and none implies another.
4. Copy the key right then. It is shown exactly once and there is no way to see it again.

The two base URLs. The examples on this page use $PEGASUS_API for the first, $PEGASUS_MCP for the second and $PEGASUS_KEY for your key, so you can export those and copy the commands as they are.

Your base URL is shown in the console, under Desarrolladores → API.

curl -s "$PEGASUS_API/v1/leads?limit=2" \
  -H "Authorization: Bearer $PEGASUS_KEY"

{
  "data": [
    {
      "id": "0f8b4d2e-1c3a-4f5b-9d7e-2a6c8b0e4f11",
      "external_id": "crm-88213",
      "first_name": "Rosa",
      "last_name": "Medina",
      "phone_e164": "+13055551234",
      "status": "queued",
      "dial_hold": false,
      "created_at": "2026-09-10T18:22:04.113Z"
    }
  ],
  "next_cursor": "MjAyNi0wOS0xMFQxODoyMjowNC4xMTNafDBmOGI0ZDJl"
}

Every request carries the key in the Authorization header. There are no query-string keys, no cookies and no sessions: a request without a valid header gets a 401 and nothing else.

Authorization: Bearer pgs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

x-pegasus-request-id: 9c1f6a2e-7b40-4d18-a3e5-51d9f0c7b2aa

Keep the x-pegasus-request-id from any response that surprises you. It is the same identifier that appears in the console log and in the request_id field of every error, and it is the first thing we will ask you for.

A live key is the production one: with dial:write, the leads it creates enter the queue and a real telephone rings. A test key writes to the same data but cannot cause contact: every lead it creates is held, and it cannot schedule appointments, whatever scopes it holds.

Scopes are a closed set. There are no wildcards and none implies another: leads:write does not let you read leads. Asking for a scope that does not exist fails at key creation, not at your first request.

Splitting the two is not decoration: leads:write creates a row, dial:write makes a phone ring in someone's house, and TCPA liability attaches to the second. An integration that only feeds a CRM cannot reach it by accident.

Every route lives under /v1. Each requires exactly one scope, resolved before the request reaches its handler: a route that names no scope does not compile, so there is no accidentally open route.

Lists answer with { data, next_cursor }. Reads by id answer with { data }. Writes answer with their own summary, described below.

Leads. The columns it returns and the parameters you can filter by:

experiment_arm is absent, and not by oversight: the arm is assigned by the platform, and nothing about a control group is the caller's business.

Calls. Each attempt, with its outcome and duration:

Conversions. An objective declares which variables it gathers and the conversion stores them in facts, so the shape of that object depends on objective_key and objective_version — both ride on the same row so you can read it without guessing:

Creating leads. Accepts a bare object or { leads: [...] }, up to 500 per request:

{
  "created": 2,
  "duplicate": 1,
  "rejected": 0,
  "dialing": "queued",
  "held_by_request": 1,
  "results": [
    { "status": "created",   "external_id": "crm-88213", "lead_id": "0f8b4d2e-…" },
    { "status": "created",   "external_id": "crm-88214", "lead_id": "7a2c1b90-…" },
    { "status": "duplicate", "external_id": "crm-88213",
      "reason": "a live lead already has this number" }
  ]
}

Each row carries status created, duplicate or rejected. A duplicate says which of the two rules caught it — the external_id was already received, or a live lead already has that number — and a rejected carries the reason the database gave. dialing is the key's verdict for the whole batch: queued if these leads enter the queue, held if not. held_by_request counts the ones you held with hold even though the key could have dialed. Read dialing rather than inferring it from scopes.

Scheduling an appointment. Two required fields:

Every error answers with the same shape. Branch on error, which is a stable code, never on message, which is a sentence for humans and may change.

{
  "error": "invalid_parameter",
  "message": "A query parameter was not understood.",
  "request_id": "9c1f6a2e-7b40-4d18-a3e5-51d9f0c7b2aa",
  "detail": "created_after"
}

429 is reserved and not emitted yet. Handle it now anyway: when a limiter exists, your integration will not have to change to find out.

503 principal_unavailable is ours and it is retryable. 500 internal is ours too: keep the request_id and tell us.

Every list orders by (created_at desc, id desc) and pages by cursor. There is no offset and no page, deliberately: leads keep arriving while you walk the pages, and an offset would let each new lead push a row from page 2 to page 3 where you never see it.

The id breaks ties, because two leads imported in the same millisecond are common and a cursor that cannot separate them either repeats rows or skips them.

async function* allLeads(base, key, params = {}) {
  let cursor = null;
  do {
    const qs = new URLSearchParams({ ...params, limit: "100" });
    if (cursor) qs.set("cursor", cursor);

    const res = await fetch(`${base}/v1/leads?${qs}`, {
      headers: { Authorization: `Bearer ${key}` },
    });
    if (!res.ok) {
      const body = await res.json();
      throw new Error(`${body.error} (request ${body.request_id})`);
    }

    const page = await res.json();
    yield* page.data;
    cursor = page.next_cursor;
  } while (cursor);
}

next_cursor comes back null when the page returned fewer rows than the limit you asked for, which is how you know you reached the end. Even so, stop on next_cursor rather than by counting rows: it is one condition, and it does not change if we ever page differently.

Register an https endpoint in the console, check the events you care about, and we POST a signed request each time one happens. The signing secret is shown exactly once, like the key.

The event set is closed. An event type is a promise: once somebody's CRM switches on qualification.passed, renaming it breaks someone's payroll. There are no custom events.

{
  "id": "3f9a71c2-5d84-4e02-9b6f-8c1d20a7e534",
  "type": "qualification.passed",
  "organization_id": "b41d7e08-2c6f-4a91-8de3-05f7c1a9b662",
  "delivery_id": "c7e0a913-4f52-4b88-9a1d-6e3b027fd845",
  "data": {
    "conversion_id": "18d5c4a7-9e31-4026-b7fa-3c08e5192d74",
    "lead_id": "0f8b4d2e-1c3a-4f5b-9d7e-2a6c8b0e4f11",
    "operator_id": "5a9e2c71-08b4-4d63-9f27-1ac6d0b85e39",
    "call_attempt_id": "9b3f6d20-7c18-4e55-a0d9-2f47b6c1e803",
    "passed": true,
    "failed_criterion": null,
    "schema_version": 1,
    "spoke_with_titular": true,
    "interest_confirmed": true,
    "converted_at": "2026-09-10T18:24:11.412Z"
  }
}

Notice what that payload does NOT carry: no name and no phone number. Contact fields ride on lead.created, which is the event that has them; the others refer to the lead by lead_id. If your CRM needs the phone number at qualification time, store it when lead.created arrives, or fetch it with GET /v1/leads/:id.

{
  "id": "8c40b17e-93d2-4f6a-b015-7e2ac9d3f481",
  "type": "lead.created",
  "organization_id": "b41d7e08-2c6f-4a91-8de3-05f7c1a9b662",
  "delivery_id": "e19f7b53-0a64-4c27-8db6-45f3c80e2917",
  "data": {
    "lead_id": "0f8b4d2e-1c3a-4f5b-9d7e-2a6c8b0e4f11",
    "external_id": "crm-88213",
    "first_name": "Rosa",
    "last_name": "Medina",
    "phone_e164": "+13055551234",
    "email": "rosa.medina@example.com",
    "state": "FL",
    "postal_code": "33125",
    "timezone": "America/New_York",
    "status": "queued",
    "dial_hold": false,
    "lead_source_id": "2d7c9410-63ab-4e15-8f02-9b41c7d05a68",
    "operator_id": "5a9e2c71-08b4-4d63-9f27-1ac6d0b85e39",
    "created_at": "2026-09-10T18:22:04.113Z"
  }
}

Every POST carries these headers:

We sign the string `${t}.${body}` with HMAC-SHA256 using your endpoint's secret, in hex. Verify against the raw body, byte for byte: if your framework already parsed the JSON and you re-serialized it, the signature will not match even though the content is identical.

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

const TOLERANCE_SECONDS = 300;

export function verifyPegasusSignature(secret, rawBody, header, now = Date.now()) {
  if (!header) return false;

  const parts = Object.fromEntries(
    header.split(",").map((kv) => {
      const i = kv.indexOf("=");
      return i < 0 ? [kv.trim(), ""] : [kv.slice(0, i).trim(), kv.slice(i + 1).trim()];
    }),
  );

  const t = Number(parts.t);
  const v1 = parts.v1;
  if (!Number.isFinite(t) || !/^[0-9a-f]{64}$/.test(v1 ?? "")) return false;

  // Reject a captured request replayed next week.
  if (Math.abs(Math.floor(now / 1000) - t) > TOLERANCE_SECONDS) return false;

  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");

  // Equal lengths guaranteed by the hex check above.
  return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(v1, "hex"));
}

app.post(
  "/pegasus",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const raw = req.body.toString("utf8");
    if (!verifyPegasusSignature(SECRET, raw, req.get("x-pegasus-signature"))) {
      return res.sendStatus(401);
    }

    // Answer fast, then work. We time out and retry a slow endpoint.
    res.sendStatus(200);
    enqueue(req.get("x-pegasus-event-id"), JSON.parse(raw));
  },
);

An event is attempted 6 times in total: the first delivery and 5 retries — after a minute, 5 minutes, half an hour, 2 hours and 6 hours. That is about eight hours, enough for a deploy, a certificate renewal and a night's sleep, without holding a row for a week. After 20 consecutive failures we switch the endpoint off and the console says so: somebody who moved their server should be told, not retried at forever.

Any 2xx counts as delivered. Everything else, a timeout included, counts as a failure and enters the retry ladder.

Pegasus also speaks MCP over streamable HTTP. It is the same API underneath: the same routes, the same scopes, the same key in the same header. There is no separate credential to manage.

claude mcp add --transport http pegasus \
  "$PEGASUS_MCP" \
  --header "Authorization: Bearer $PEGASUS_KEY"

The server is stateless and initiates nothing: GET answers 405 because there is no SSE stream to open, and there is no sampling and there are no subscriptions. An API refusal arrives as a tool result marked isError rather than as a transport error, so the model can read it and correct course instead of being left in the dark.