Data API for your businesses

Bring the data you see in your dashboard into your reports, dashboards or CRM. Available with Starter, Growth and Agency, including an active trial. This is a read-only API.

Download OpenAPI 3.1

Create a key in Settings

In Settings → API keys, enter a name, choose “Entire account” or a single business, and copy the key: it is shown only once. You can have five active keys and create up to ten per day per account. Revoke them at any time. Older keys remain limited to their business. Revocation and plan or payment changes take effect on the next request.

Open Settings

Authentication

Send the key in the Authorization: Bearer header. Keep it on your server. Public AI names are chatgpt, gemini, perplexity and claude; each business retains its plan permissions.

Authorization: Bearer sk_live_…

Limits and pagination

60 requests per minute and 10,000 per day per key, with an account ceiling of 30,000 per day. Revoking a key does not restore consumed quota. PDFs: 10 per minute and 50 per day per account, 20 per day per key and one at a time per account. Authentication failures are limited by IP; valid keys used in the last seven days continue to work even when that limit is reached. IPv6 addresses share a /64 quota and mapped IPv4 addresses share their original IPv4 quota. Check X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. On a 429, wait for the seconds in Retry-After.

For lists, use page (starting at 1) and limit (1–100; default 50). The offset (page − 1) × limit cannot exceed 10,000; exceeding it returns 400 invalid_query. pagination.has_more indicates another page. Use lang=es or lang=en; the default is es. Missing older translations fall back to the available text. Questions and responses retain their original language. Responses are not cached. Examples use fictional data.

Each response indicates whether your brand appears. Responses counted per question and provider.

Escape third-party text when displaying it: AI responses, sources and competitor names. sources contains only valid http(s) URLs.

Errors

401 · invalid_api_key
The API key is invalid or has been revoked.
403 · paid_plan_required
A paid plan or an active trial is required.
403 · billing_blocked
Update your account payment to continue.
404 · not_found
The resource was not found.
400 · invalid_query
Check the request filters and pagination.
429 · rate_limit_exceeded
You have reached the request limit.
503 · service_unavailable
The service is temporarily unavailable. Please try again later.
403 · workspace_key_required
The plugin needs a key for a specific business. Create one in Settings → API keys and select that business.
{
  "error": {
    "code": "not_found",
    "message": "The resource was not found."
  }
}

Available resources

Account businesses

GET /api/v1/workspaces

curl 'https://surfeo.ai/api/v1/workspaces?lang=en' \
  -H 'Authorization: Bearer YOUR_API_KEY'
{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Example Clinic",
      "url": "https://example.com",
      "sector": "health",
      "city": "Granada",
      "region": "Andalucía",
      "country": "ES",
      "language": "en",
      "plan": "growth",
      "created_at": "2026-10-01T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

Business profile and latest score

GET /api/v1/workspaces/{id}

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111?lang=en' \
  -H 'Authorization: Bearer YOUR_API_KEY'
{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Example Clinic",
    "url": "https://example.com",
    "sector": "health",
    "city": "Granada",
    "region": "Andalucía",
    "country": "ES",
    "language": "en",
    "plan": "growth",
    "created_at": "2026-10-01T10:00:00Z",
    "latest_score": {
      "audit_id": "22222222-2222-4222-8222-222222222222",
      "score": 72,
      "label": "Dominant",
      "created_at": "2026-10-01T10:00:00Z",
      "reliable": true
    }
  }
}

Score history. from and to accept ISO 8601 dates, with both bounds included. A date without a time covers the full UTC day.

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

Filters: from, to

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/scores?lang=en' \
  -H 'Authorization: Bearer YOUR_API_KEY'
{
  "data": [
    {
      "audit_id": "22222222-2222-4222-8222-222222222222",
      "score": 72,
      "label": "Dominant",
      "created_at": "2026-10-01T10:00:00Z",
      "reliable": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

Business questions

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

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/questions?lang=en' \
  -H 'Authorization: Bearer YOUR_API_KEY'
{
  "data": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "text": "Which clinics are in Granada?",
      "language": "en",
      "active": true,
      "custom": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

Question mention history

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

Filters: audit_id, provider, mentioned

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/questions/33333333-3333-4333-8333-333333333333/history?lang=en' \
  -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
  }
}

AI responses from the latest completed audit by default. Use audit_id for another completed audit, and provider or mentioned=true|false to filter.

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

Filters: audit_id, provider, mentioned

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/responses?lang=en' \
  -H 'Authorization: Bearer YOUR_API_KEY'
{
  "data": [
    {
      "question_id": "33333333-3333-4333-8333-333333333333",
      "question": "Which clinics are in Granada?",
      "provider": "chatgpt",
      "mentioned": true,
      "position": 2,
      "sentiment": "positive",
      "competitors": [
        "Neighbor Clinic"
      ],
      "sources": [
        "https://example.com/"
      ],
      "response": "Example Clinic provides care in Granada.",
      "created_at": "2026-10-01T10:00:00Z",
      "audit_id": "22222222-2222-4222-8222-222222222222"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

Competitors and your brand in the latest completed audit

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

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/competitors?lang=en' \
  -H 'Authorization: Bearer YOUR_API_KEY'
{
  "data": {
    "audit_id": "22222222-2222-4222-8222-222222222222",
    "brand": {
      "name": "Example Clinic",
      "url": "https://example.com",
      "mentions": 6,
      "mention_rate": 0.75
    },
    "competitors": [
      {
        "name": "Neighbor Clinic",
        "url": "https://example.org",
        "main": true,
        "mentions": 4,
        "mention_rate": 0.5
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

Recommendations. Filter by status=pending|completed|verified.

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

Filters: status

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/recommendations?lang=en' \
  -H 'Authorization: Bearer YOUR_API_KEY'
{
  "data": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "title": "Complete the contact page",
      "description": "Publish your contact details.",
      "instructions": "Add your address and opening hours.",
      "category": "content",
      "priority": 1,
      "difficulty": "easy",
      "estimated_impact": "medium",
      "target_page": "https://example.com/contact",
      "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
  }
}

Completed audits and report links

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

curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/audits?lang=en' \
  -H 'Authorization: Bearer YOUR_API_KEY'
{
  "data": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "completed_at": "2026-10-01T10:00:00Z",
      "score": 72,
      "summary": "Your visibility has improved.",
      "quick_win": {
        "action": "Publish your opening hours on your website.",
        "impact": "medium",
        "effort": "easy"
      },
      "report_url": "/api/v1/workspaces/11111111-1111-4111-8111-111111111111/audits/22222222-2222-4222-8222-222222222222/report.pdf?lang=en"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

PDF report for a completed audit

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=en' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -o report.pdf

The response is an application/pdf file. Save the download as report.pdf.

Business data (legacy)

GET /api/v1/data

Legacy. Requires a key for a specific business and a paid plan or active trial, with payments up to date. Account keys receive 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": "Example Clinic",
      "url": "https://example.com",
      "plan": "growth",
      "sector": "health",
      "city": "Granada",
      "region": "Andalucía",
      "country": "ES"
    },
    "scores": [
      {
        "overall_score": 72,
        "label": "good",
        "created_at": "2026-10-01T10:00:00Z"
      }
    ],
    "recommendations": [
      {
        "title": "Complete the contact page",
        "title_en": "Complete the contact page",
        "description": "Publish your contact details.",
        "description_en": "Publish your contact details.",
        "category": "content",
        "priority": 1,
        "difficulty": "easy"
      }
    ],
    "last_audit": {
      "status": "completed",
      "completed_at": "2026-10-01T10:00:00Z"
    }
  }
}

AI overview (legacy)

GET /api/v1/providers

Legacy. Requires a key for a specific business and a paid plan or active trial, with payments up to date. Account keys receive 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
      }
    ]
  }
}

Request a free diagnostic (public)

POST /api/v1/quick-audit

Public, no key required. Diagnostics are subject to IP, domain and daily capacity limits. Status requests have a separate IP limit. Reaching a limit returns 429; try again later.

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

Free diagnostic status (public)

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

Public, no key required. Diagnostics are subject to IP, domain and daily capacity limits. Status requests have a separate IP limit. Reaching a limit returns 429; try again later.

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

For agencies

Build your own reports from score history, bring clients together in your dashboard and add recommendations to your CRM. Download completed audit PDFs with your configured white label branding. You build the integration with your tools.