Documentación

La API de Pegasus es REST sobre HTTPS, con JSON en los dos sentidos. La misma llave abre la API REST y el servidor MCP; no hay dos credenciales que administrar.

1. Entra a la consola y abre Desarrolladores → Llaves.
2. Crea una llave. Elige el entorno test mientras desarrollas: una llave test nunca hace sonar un teléfono.
3. Marca solo los permisos que tu integración necesita. No hay comodines y ninguno implica a otro.
4. Copia la llave en ese momento. Se muestra una sola vez y no hay forma de volver a verla.

Las dos direcciones base. Los ejemplos de esta página usan $PEGASUS_API para la primera, $PEGASUS_MCP para la segunda y $PEGASUS_KEY para tu llave, así que puedes exportarlas y copiar los comandos tal cual.

Tu dirección base aparece en la consola, en 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"
}

Toda petición lleva la llave en la cabecera Authorization. No hay llaves por query string, ni cookies, ni sesiones: una petición sin cabecera válida recibe 401 y nada más.

Authorization: Bearer pgs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

Guarda el x-pegasus-request-id de cualquier respuesta que te sorprenda. Es el mismo identificador que aparece en el registro de la consola y en el campo request_id de todo error, y es lo primero que te vamos a pedir.

Una llave live es la de producción: con dial:write, los leads que crea entran a la cola y suena un teléfono real. Una llave test escribe en los mismos datos pero no puede causar contacto: todo lead que crea queda retenido, y no puede agendar citas, tenga los permisos que tenga.

Los permisos son un conjunto cerrado. No hay comodines y ninguno implica a otro: leads:write no te deja leer leads. Pedir un permiso que no existe falla al crear la llave, no en la primera petición.

Separar los dos permisos no es decoración: leads:write crea una fila, dial:write hace sonar un teléfono en casa de alguien, y la responsabilidad legal bajo TCPA se aplica al segundo. Una integración que solo alimenta un CRM no puede llegar ahí por accidente.

Toda ruta vive bajo /v1. Cada una exige exactamente un permiso, resuelto antes de que la petición llegue a su manejador: una ruta sin permiso no compila, así que no existe una ruta abierta por descuido.

Las listas responden { data, next_cursor }. Las lecturas por id responden { data }. Las escrituras responden su propio resumen, descrito más abajo.

Leads. Las columnas que devuelve y los parámetros con los que puedes filtrar:

experiment_arm no está y no es un olvido: el brazo lo asigna la plataforma, y nada de un grupo de control es asunto de quien lo consume.

Llamadas. Cada intento, con su resultado y su duración:

Conversiones. Un objetivo declara qué variables recoge, y la conversión las guarda en facts, así que la forma de ese objeto depende de objective_key y objective_version —los dos vienen en la misma fila para que puedas leerlo sin adivinar:

Crear leads. Acepta un objeto suelto o { leads: [...] }, hasta 500 por petición:

{
  "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" }
  ]
}

Cada fila trae status created, duplicate o rejected. Un duplicate explica cuál de las dos reglas lo atrapó —el external_id ya recibido, o un lead vivo con ese mismo número— y un rejected trae el motivo tal cual lo dio la base de datos. dialing es el veredicto de la llave para todo el lote: queued si estos leads entran a la cola, held si no. held_by_request cuenta los que tú retuviste con hold aunque la llave sí podía marcar. Lee dialing en vez de suponerlo a partir de los permisos.

Agendar una cita. Dos campos obligatorios:

Todo error responde con la misma forma. Ramifica sobre error, que es un código estable, nunca sobre message, que es una frase para humanos y puede cambiar.

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

429 está reservado y todavía no lo emitimos. Manéjalo ahora de todos modos: cuando exista un limitador, tu integración no tendrá que cambiar para enterarse.

503 principal_unavailable es nuestro y es reintentable. 500 internal también es nuestro: guarda el request_id y escríbenos.

Toda lista ordena por (created_at desc, id desc) y pagina por cursor. No hay offset ni page, y es a propósito: mientras recorres las páginas siguen entrando leads, y un offset habría hecho que cada lead nuevo empujara una fila de la página 2 a la 3 sin que la vieras nunca.

El id desempata, porque dos leads importados en el mismo milisegundo son comunes y un cursor que no puede distinguirlos repite filas o las salta.

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 viene en null cuando la página devolvió menos filas que el limit que pediste, que es como sabes que llegaste al final. Aun así, detente por next_cursor y no contando filas: es una sola condición y no cambia si algún día paginamos distinto.

Registra un endpoint https en la consola, marca los eventos que te interesan y te mandamos un POST firmado cada vez que ocurra uno. El secreto de firma se muestra una sola vez, igual que la llave.

El conjunto de eventos es cerrado. Un tipo de evento es una promesa: en cuanto el CRM de alguien enciende qualification.passed, renombrarlo le rompe la nómina a otra persona. No hay eventos personalizados.

{
  "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"
  }
}

Fíjate en lo que NO trae ese payload: ni nombre ni teléfono. Los datos de contacto viajan en lead.created, que es el evento que los tiene; los demás se refieren al lead por lead_id. Si tu CRM necesita el teléfono al calificar, guárdalo cuando llegue lead.created o pídelo con 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"
  }
}

Cada POST lleva estas cabeceras:

Firmamos la cadena `${t}.${cuerpo}` con HMAC-SHA256 usando el secreto de tu endpoint, en hexadecimal. Verifica sobre el cuerpo crudo, byte por byte: si tu framework ya parseó el JSON y lo volviste a serializar, la firma no va a coincidir aunque el contenido sea el mismo.

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));
  },
);

Un evento se intenta 6 veces en total: el primer envío y 5 reintentos, al minuto, a los 5 minutos, a la media hora, a las 2 horas y a las 6 horas. Son unas ocho horas, suficiente para un despliegue, la renovación de un certificado y una noche de sueño, sin dejar una fila colgada una semana. Después de 20 fallos seguidos apagamos el endpoint y la consola lo dice: a quien movió su servidor hay que avisarle, no reintentarle para siempre.

Cualquier respuesta 2xx cuenta como entregada. Todo lo demás, incluido un tiempo de espera agotado, cuenta como fallo y entra a la escalera de reintentos.

Pegasus también habla MCP sobre HTTP (streamable). Es la misma API detrás: las mismas rutas, los mismos permisos, la misma llave en la misma cabecera. No hay una credencial aparte que administrar.

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

El servidor no tiene estado y no manda mensajes por su cuenta: GET responde 405 porque no hay stream SSE que abrir, y no hay sampling ni suscripciones. Una negativa de la API llega como resultado de herramienta marcado isError, no como un error de transporte, para que el modelo pueda leerla y corregir en vez de quedarse sin saber qué pasó.