API de datos para tus negocios

Lleva los datos que ves en tu panel a tus informes, paneles o CRM. Disponible con Starter, Growth y Agencia, incluida la prueba activa. La API es de solo lectura.

Descargar OpenAPI 3.1

Crea una clave en Configuración

En Configuración → Claves API, ponle un nombre, elige «Toda la cuenta» o un solo negocio y copia la clave: se muestra una sola vez. Puedes tener cinco claves activas y crear hasta diez al día por cuenta. Puedes revocarlas cuando quieras. Las claves antiguas siguen limitadas a su negocio. Una revocación o un cambio de plan o de pago se aplica en la siguiente petición.

Abrir Configuración

Autenticación

Envía la clave en la cabecera Authorization: Bearer. Guárdala en tu servidor. Los nombres públicos de IA son chatgpt, gemini, perplexity y claude; cada negocio conserva los permisos de su plan.

Authorization: Bearer sk_live_…

Límites y paginación

60 peticiones por minuto y 10.000 al día por clave, con un máximo de 30.000 al día por cuenta. Revocar una clave no recupera el cupo consumido. PDF: 10 por minuto y 50 al día por cuenta, 20 al día por clave y uno a la vez por cuenta. Los fallos de autenticación se limitan por IP; las claves válidas usadas en los últimos siete días siguen funcionando aunque se alcance ese límite. Las direcciones IPv6 comparten cupo por /64 y las IPv4 mapeadas comparten el de su IPv4 original. Consulta X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Ante un 429, espera los segundos de Retry-After.

En las listas, usa page (desde 1) y limit (1–100; 50 por defecto). El desplazamiento (page − 1) × limit no puede superar 10.000; si lo supera, recibirás 400 invalid_query. pagination.has_more indica si hay otra página. Usa lang=es o lang=en; por defecto es. Si falta una traducción antigua, se usa el texto disponible. Las preguntas y respuestas conservan su idioma original. Las respuestas no se guardan en caché. Los ejemplos son ficticios.

Cada respuesta indica si tu marca aparece. Los totales cuentan una respuesta por pregunta y proveedor.

Escapa los textos de terceros al mostrarlos: respuestas de las IAs, fuentes y nombres de competidores. sources solo contiene URLs http(s) válidas.

Errores

401 · invalid_api_key: La clave API no es válida o ha sido revocada.
403 · paid_plan_required: Necesitas un plan de pago o una prueba activa.
403 · billing_blocked: Actualiza el pago de tu cuenta para continuar.
404 · not_found: No se ha encontrado el recurso.
400 · invalid_query: Revisa los filtros y la paginación de la petición.
429 · rate_limit_exceeded: Has alcanzado el límite de peticiones.
503 · service_unavailable: El servicio no está disponible temporalmente. Vuelve a intentarlo más tarde.
403 · workspace_key_required: El plugin necesita una clave de un negocio concreto. Créala en Configuración → Claves API y elige ese negocio.

{
  "error": {
    "code": "not_found",
    "message": "No se ha encontrado el recurso."
  }
}

Recursos disponibles

Negocios de la cuenta

GET /api/v1/workspaces

curl 'https://surfeo.ai/api/v1/workspaces?lang=es' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Clínica Ejemplo",
      "url": "https://example.com",
      "sector": "health",
      "city": "Granada",
      "country": "ES",
      "language": "es",
      "plan": "growth",
      "created_at": "2026-10-01T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

Ficha y última nota

GET /api/v1/workspaces/{id}

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111?lang=es' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Clínica Ejemplo",
    "url": "https://example.com",
    "sector": "health",
    "city": "Granada",
    "country": "ES",
    "language": "es",
    "plan": "growth",
    "created_at": "2026-10-01T10:00:00Z",
    "latest_score": {
      "audit_id": "22222222-2222-4222-8222-222222222222",
      "score": 72,
      "label": "Dominante",
      "created_at": "2026-10-01T10:00:00Z",
      "reliable": true
    }
  }
}

Histórico de notas. from y to aceptan fechas ISO 8601, con ambos extremos incluidos. Una fecha sin hora abarca el día completo en UTC.

GET /api/v1/workspaces/{id}/scores

Filtros: from, to

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/scores?lang=es' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "audit_id": "22222222-2222-4222-8222-222222222222",
      "score": 72,
      "label": "Dominante",
      "created_at": "2026-10-01T10:00:00Z",
      "reliable": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

Preguntas del negocio

GET /api/v1/workspaces/{id}/questions

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/questions?lang=es' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "text": "¿Qué clínicas hay en Granada?",
      "language": "es",
      "active": true,
      "custom": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

Histórico de menciones de una pregunta

GET /api/v1/workspaces/{id}/questions/{questionId}/history

Filtros: audit_id, provider, mentioned

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/questions/33333333-3333-4333-8333-333333333333/history?lang=es' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "audit_id": "22222222-2222-4222-8222-222222222222",
      "question_id": "33333333-3333-4333-8333-333333333333",
      "provider": "chatgpt",
      "mentioned": true,
      "position": 2,
      "sentiment": "positive",
      "created_at": "2026-10-01T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

Respuestas de las IAs en la última auditoría completada por defecto. Usa audit_id para consultar otra auditoría completada, y provider o mentioned=true|false para filtrar.

GET /api/v1/workspaces/{id}/responses

Filtros: audit_id, provider, mentioned

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/responses?lang=es' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "question_id": "33333333-3333-4333-8333-333333333333",
      "question": "¿Qué clínicas hay en Granada?",
      "provider": "chatgpt",
      "mentioned": true,
      "position": 2,
      "sentiment": "positive",
      "competitors": [
        "Clínica Vecina"
      ],
      "sources": [
        "https://example.com/"
      ],
      "response": "Clínica Ejemplo ofrece atención en Granada.",
      "created_at": "2026-10-01T10:00:00Z",
      "audit_id": "22222222-2222-4222-8222-222222222222"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

Competidores y tu marca en la última auditoría completada

GET /api/v1/workspaces/{id}/competitors

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/competitors?lang=es' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": {
    "audit_id": "22222222-2222-4222-8222-222222222222",
    "brand": {
      "name": "Clínica Ejemplo",
      "url": "https://example.com",
      "mentions": 6,
      "mention_rate": 0.75
    },
    "competitors": [
      {
        "name": "Clínica Vecina",
        "url": "https://example.org",
        "main": true,
        "mentions": 4,
        "mention_rate": 0.5
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

Recomendaciones. Filtra por status=pending|completed|verified.

GET /api/v1/workspaces/{id}/recommendations

Filtros: status

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/recommendations?lang=es' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "title": "Completa la página de contacto",
      "description": "Publica tus datos de contacto.",
      "instructions": "Añade dirección y horario.",
      "category": "content",
      "priority": 1,
      "difficulty": "easy",
      "estimated_impact": "medium",
      "target_page": "https://example.com/contacto",
      "completed": true,
      "verified": true,
      "created_at": "2026-10-01T10:00:00Z",
      "completed_at": "2026-10-01T10:00:00Z",
      "verified_at": "2026-10-01T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

Auditorías completadas y enlaces al informe

GET /api/v1/workspaces/{id}/audits

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/audits?lang=es' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "completed_at": "2026-10-01T10:00:00Z",
      "score": 72,
      "summary": "Tu presencia ha mejorado.",
      "quick_win": {
        "action": "Publica el horario en tu web.",
        "impact": "medium",
        "effort": "easy"
      },
      "report_url": "/api/v1/workspaces/11111111-1111-4111-8111-111111111111/audits/22222222-2222-4222-8222-222222222222/report.pdf?lang=es"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

Informe PDF de una auditoría completada

GET /api/v1/workspaces/{id}/audits/{auditId}/report.pdf

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/audits/22222222-2222-4222-8222-222222222222/report.pdf?lang=es' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -o informe.pdf

La respuesta es un fichero application/pdf. Guarda la descarga como informe.pdf.

Datos del negocio (heredada)

GET /api/v1/data

Heredada. Requiere una clave de un negocio concreto y un plan de pago o prueba activa, con los pagos al día. Las claves de cuenta reciben 403 workspace_key_required.

curl 'https://surfeo.ai/api/v1/data' -H 'Authorization: Bearer YOUR_BUSINESS_API_KEY'

{
  "data": {
    "workspace": {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Clínica Ejemplo",
      "url": "https://example.com",
      "plan": "growth",
      "sector": "health",
      "city": "Granada",
      "country": "ES"
    },
    "scores": [
      {
        "overall_score": 72,
        "label": "good",
        "created_at": "2026-10-01T10:00:00Z"
      }
    ],
    "recommendations": [
      {
        "title": "Completa la página de contacto",
        "title_en": "Complete the contact page",
        "description": "Publica tus datos de contacto.",
        "description_en": "Publish your contact details.",
        "category": "content",
        "priority": 1,
        "difficulty": "easy"
      }
    ],
    "last_audit": {
      "status": "completed",
      "completed_at": "2026-10-01T10:00:00Z"
    }
  }
}

Resumen por IA (heredada)

GET /api/v1/providers

Heredada. Requiere una clave de un negocio concreto y un plan de pago o prueba activa, con los pagos al día. Las claves de cuenta reciben 403 workspace_key_required.

curl 'https://surfeo.ai/api/v1/providers' -H 'Authorization: Bearer YOUR_BUSINESS_API_KEY'

{
  "data": {
    "providers": [
      {
        "provider": "chatgpt",
        "label": "ChatGPT",
        "locked": false,
        "mention_rate": 75,
        "avg_position": 2,
        "dominant_sentiment": "positive",
        "total_responses": 4
      }
    ]
  }
}

Solicitar un diagnóstico gratuito (pública)

POST /api/v1/quick-audit

Pública, sin clave. Los diagnósticos tienen límites por IP, por dominio y de capacidad diaria. El estado tiene su propio límite por IP. Si se alcanza un límite, recibirás 429; vuelve a intentarlo más tarde.

curl 'https://surfeo.ai/api/v1/quick-audit' -X POST -H 'Content-Type: application/json' -d '{"url":"https://example.com"}'

{
  "data": {
    "audit_id": "22222222-2222-4222-8222-222222222222",
    "status": "pending",
    "status_url": "/api/v1/quick-audit/22222222-2222-4222-8222-222222222222/status"
  }
}

Estado de un diagnóstico gratuito (pública)

GET /api/v1/quick-audit/{id}/status

curl 'https://surfeo.ai/api/v1/quick-audit/11111111-1111-4111-8111-111111111111/status'

{
  "data": {
    "status": "pending",
    "score": null,
    "label": null,
    "providers": null,
    "findings_preview": null,
    "sector_benchmark": null,
    "signup_url": null
  }
}

Para agencias

Crea informes propios con el histórico de notas, reúne varios clientes en tu panel y añade recomendaciones al CRM. Descarga los PDF de auditorías completadas con la marca blanca que tengas configurada. La integración con tus herramientas corre por tu cuenta.