Endpoints Públicos
Los endpoints /public/* están diseñados para invocarse desde un navegador mediante el SDK de JavaScript. Se autentican con una write key (no una API key) y validan el Origin de la solicitud contra los dominios permitidos del espacio de trabajo.
| Encabezado de autenticación | Dónde utilizarlo |
|---|---|
X-Write-Key: <key> | Todos los endpoints públicos |
La write key tiene alcance de organización (se resuelve a una organización) y el encabezado Origin debe coincidir con un dominio registrado en la configuración del stream de la write key. Las llamadas del lado del servidor sin encabezado Origin omiten la verificación de dominio, pero igualmente requieren una clave válida.
Estos endpoints también están encapsulados por el SDK:
| Endpoint | Wrapper del SDK |
|---|---|
POST /public/enrich/lookup | Formulario progresivo <G8Form /> |
GET /public/visitors/company | g8.visitors.identify() |
GET /public/visitors/score | g8.visitors.score() |
GET /public/signals/company | g8.signals.company() |
POST /public/copilot/chat | g8.copilot.ask() |
Para esquemas legibles por máquina, consulte la documentación interactiva de la API.
Autenticación
Todas las solicitudes deben incluir la write key:
curl "https://be.graph8.com/api/v1/public/visitors/company" \ -H "X-Write-Key: $WRITE_KEY" \ -H "Origin: https://yoursite.com"Errores
| Estado | Significado |
|---|---|
401 | X-Write-Key ausente, clave inválida o clave no vinculada a una organización |
403 | Origin no figura entre los dominios permitidos del espacio de trabajo |
Consulta de contacto (formulario progresivo)
POST /public/enrich/lookup
Busca un contacto por correo electrónico e indica qué campos del formulario ya conoce graph8. Lo utiliza <G8Form /> para ocultar los campos precargados y solicitar únicamente la información faltante.
El conjunto de campos de formulario admitidos es fijo: name, company, phone, title, website.
Cuerpo de la solicitud
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
email | string | Sí | Correo electrónico a consultar |
Ejemplo
curl -X POST "https://be.graph8.com/api/v1/public/enrich/lookup" \ -H "X-Write-Key: $WRITE_KEY" \ -H "Origin: https://yoursite.com" \ -H "Content-Type: application/json" \Respuesta
{ "data": { "found": true, "known_fields": { "name": "Jane Smith", "company": "Acme Inc", "title": "VP of Engineering", "website": "https://acme.com" }, "missing_fields": ["phone"] }}Si no se encuentra coincidencia, found es false y missing_fields lista los 5 campos.
Identificación de empresa del visitante
GET /public/visitors/company
Resuelve la dirección IP del solicitante a una empresa utilizando la tabla ip_2_company. graph8 lee la IP desde X-Forwarded-For, luego X-Real-IP y, por último, la conexión directa.
Si se encuentra una coincidencia de dominio, la respuesta se enriquece con industria, número de empleados, ciudad y país provenientes del índice mashup de OpenSearch.
Ejemplo
curl "https://be.graph8.com/api/v1/public/visitors/company" \ -H "X-Write-Key: $WRITE_KEY" \ -H "Origin: https://yoursite.com"Respuesta
{ "data": { "company_name": "Acme Inc", "company_domain": "acme.com", "industry": "Technology", "employee_count": "500", "city": "San Francisco", "country": "US", "confidence": 0.85 }}Si la IP no puede resolverse, todos los campos son null salvo confidence, que es 0.0.
Puntuación del visitante
GET /public/visitors/score
Devuelve una puntuación de interacción (0-100) para el visitante actual basada en sus eventos de los últimos 7 días.
Ejemplo
curl "https://be.graph8.com/api/v1/public/visitors/score" \ -H "X-Write-Key: $WRITE_KEY" \ -H "Origin: https://yoursite.com"Respuesta
{ "data": { "engagement": 65, "intent": "medium", "signals": ["multi_page_visit", "high_activity"] }}intent es high (>=70), medium (>=30) o low. Las señales se derivan de la diversidad de páginas y el volumen de eventos.
Señales de intención de empresa
GET /public/signals/company
Devuelve señales de intención de compra para un dominio de empresa (no el visitante actual). Agrega los eventos de los últimos 30 días de cualquier visitante resuelto a ese dominio.
Parámetros de consulta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
domain | string | Sí | Dominio de la empresa (p. ej. acme.com) |
Ejemplo
curl "https://be.graph8.com/api/v1/public/signals/company?domain=acme.com" \ -H "X-Write-Key: $WRITE_KEY" \ -H "Origin: https://yoursite.com"Respuesta
{ "data": { "domain": "acme.com", "score": 75, "intent": "high", "signals": [ "pricing_page", "demo_page", "multiple_visitors", "deep_exploration" ], "last_seen": "2026-04-15T14:30:00Z" }}La lista signals[] se deriva de las rutas de página (/pricing, /demo, /book, /case-stud*), la cantidad de visitantes únicos (>=3), la cantidad de páginas únicas (>=5) y el total de eventos (>=20).
Chat con Copilot
POST /public/copilot/chat
Envía un mensaje al Copilot de graph8 con alcance a la base de conocimiento de la organización (documentos de contexto global, brand brief, preguntas frecuentes). A diferencia del Copilot autenticado, este endpoint no dispone de herramientas de administración: solo puede leer del índice RAG de la organización.
Cuerpo de la solicitud
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
message | string | Sí | Mensaje del usuario |
session_id | string | No | ID de sesión de conversación (se devuelve en la respuesta) |
context | object | No | Contexto opcional del lado del cliente |
Ejemplo
curl -X POST "https://be.graph8.com/api/v1/public/copilot/chat" \ -H "X-Write-Key: $WRITE_KEY" \ -H "Origin: https://yoursite.com" \ -H "Content-Type: application/json" \ -d '{"message": "Do you offer SOC 2 compliance?"}'Respuesta
{ "data": { "response": "Yes - Acme is SOC 2 Type II compliant as of...", "session_id": null, "sources": [ {"title": "Security FAQ", "type": "faq"} ] }}Cuando la búsqueda RAG o la generación de IA falla, el endpoint devuelve una cadena de respaldo en lugar de un error 5xx: revise sources para determinar si se recuperó contexto real.