---
title: "Surfer API Examples of Use"
description: "A few examples of our API in action!"
url: https://docs.surferseo.com/en/articles/8201326-surfer-api-examples-of-use
collection: "API"
updated: 2026-10-26
language: en
alternates: [fr, de]
---

# Surfer API Examples of Use

A few examples of our API in action!

> **Warning:** Heads up: These examples use v1 endpoints. v1 still works but is deprecated. If you're building a new integration, use the v2 paths below instead:

## **V1 → V2 endpoint mapping:**

<table data-id="355ea1cd-5260-45c0-a3c5-1dc3b4e87f8c" style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1"><p data-id="1cc5e1a1-f955-43bd-90f9-5430ec39baea">What you're doing</p></td><td colspan="1" rowspan="1"><p data-id="7161f9c2-1d56-495a-9271-3cb97fe05a7f">V1 (deprecated)</p></td><td colspan="1" rowspan="1"><p data-id="0908e157-149f-4dc2-8eac-8ffb7faa8f56">V2 (recommended)</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="6917db75-abdb-4f91-97a3-ab5dd0db9193">Create Content Editor</p></td><td colspan="1" rowspan="1"><p data-id="22cf60e4-143e-48c3-b3f5-39daa27499f3"><code>POST /api/v1/content_editors</code></p></td><td colspan="1" rowspan="1"><p data-id="2f46985e-48af-45c6-acfd-2bad6182c93c"><code>POST /api/v2/workspaces/{workspace_id}/content_editors</code></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="266f4b53-6b78-42dc-8e40-abd146c7577d">Get Content Editor status</p></td><td colspan="1" rowspan="1"><p data-id="0f3f2405-4571-48cf-b3e8-e3028cde3c48"><code>GET /api/v1/content_editors/{id}</code></p></td><td colspan="1" rowspan="1"><p data-id="f7590470-8de3-4a01-9087-617f860ebf87"><code>GET /api/v2/workspaces/{workspace_id}/content_editors/{id}</code></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="5be415b7-bcfe-43fc-b8b1-4885c321cc6c">Get Content Editor content</p></td><td colspan="1" rowspan="1"><p data-id="2a96bd6b-1c31-4463-bd54-d823b09138e5"><code>GET /api/v1/content_editors/{id}/content</code></p></td><td colspan="1" rowspan="1"><p data-id="ce76d9bf-feb6-4fb3-8466-e41b7e3f19c9"><code>GET /api/v2/workspaces/{workspace_id}/content_editors/{id}/content</code></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="b105eea8-1857-4092-b390-aaede2ffa984">Get NLP terms</p></td><td colspan="1" rowspan="1"><p data-id="8b6e9f05-a9da-4ad9-8d56-3f1a06927d59"><code>GET /api/v1/content_editors/{id}/terms</code></p></td><td colspan="1" rowspan="1"><p data-id="4a39a197-405b-45d5-a4b8-3c02f36f87ff"><code>GET /api/v2/workspaces/{workspace_id}/content_editors/{id}/seo_guidelines/terms</code></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="7f904c3b-e53e-4007-9b02-8161b139e341">Get Content Score</p></td><td colspan="1" rowspan="1"><p data-id="fc128e89-3e90-4aef-b422-6fcca5b321ee"><code>GET /api/v1/content_editors/{id}/content_score</code></p></td><td colspan="1" rowspan="1"><p data-id="06191417-c2cb-4f71-9062-ad691927bd01"><code>GET /api/v2/workspaces/{workspace_id}/content_editors/{id}/seo_guidelines/score</code></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="2a567f01-052c-4181-8612-5084471dffd3">List Content Editors</p></td><td colspan="1" rowspan="1"><p data-id="a3c350da-7581-4b55-a8b7-6ff5c03e0bfe"><code>GET /api/v1/content_editors</code></p></td><td colspan="1" rowspan="1"><p data-id="331aef83-dad4-4760-9578-2a4fc71172f3"><code>GET /api/v2/content_editors</code> or <code>GET /api/v2/workspaces/{workspace_id}/content_editors</code></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="78ef2195-f133-4acb-8353-9c573e9d26e5">List workspaces</p></td><td colspan="1" rowspan="1"><p data-id="f09b3f43-7fd2-4ff3-95db-c3c2ec315cfa"><code>GET /api/v1/workspaces</code></p></td><td colspan="1" rowspan="1"><p data-id="5c3cd22a-4c96-4fb8-b409-0533ed85f3fc"><code>GET /api/v2/workspaces</code></p></td></tr></tbody></table>

SERP Analyzer, Audit, AI Detector, and Humanizer remain on V1 — V2 equivalents are not yet available for those tools.

* * *

Here are a couple of workflows that can benefit from Surfer API integration via your custom app or 3rd party solutions like Zapier or Bubble.io:

## Creating multiple queries and sharing access links

Via API, you can automate the creation of queries for Content Editor, Audit, and SERP Analyzer. Then, based on our responses, you can create web-app access links.

For example, you might have a Google Sheet with a list of keywords you want to rank for, and you want to create new articles using Content Editor.  
​

In such an instance, you could:

1.  Format your sheet so that each row contains ranking keywords and the location of your target audience.
    
2.  For each row, extract keywords and location data and send them in using _POST_ request to _/api/v1/content\_editors_ endpoint.
    
    _Tip: Remember that keywords should always be an array, even if you aim to optimize for only one keyword_.
    
3.  In response, you will get:
    
    ```javascript
    {
    "state": "scheduled",
    "permalink_hash": "kKi7n3pkRk7Gw5cxKDiBAbCAybnDTt2z",
    "id": 5632898
    }
    ```
    
    You can now create query access links by:
    
    -   joining "[_https://app.surferseo.com/drafts/_](https://app.surferseo.com/drafts/)_" + "5632898"_ strings - this will result in a private link that the account owner or organization member can access
        
    -   joining _"_[_https://app.surferseo.com/drafts/s/_](https://app.surferseo.com/drafts/s/)_" + "kKi7n3pkRk7Gw5cxKDiBA"_ strings will result in anyone accessing a public share link.
        
4.  Share them with your team and external writers, or paste them in the original sheet you used for keyword input - whatever your preferred workflow requires.
    

* * *

## Publishing written content to your CMS

Via API, you can get a clean HTML version of your Content Editor draft. You can then send it to Google Docs or your CMS via custom integration.

To get Editor query content, all you have to do is:

1.  Locate the _"id"_ of the Content Editor query you want to download content from.  
    ​_Tip: If you didn't store ID for the query anywhere, just find it via web-app and copy the last_ [_https://app.surferseo.com/drafts/_](https://app.surferseo.com/drafts/)_5632898_
    
2.  Send a _GET_ request to _/api/v1/content\_editors/:id/content_ specifying the "id" you found, here _/api/v1/content\_editors/5632898/content_
    
3.  Store the response.
    

Depending on your target text editor/CMS, you might need to parse the HTML we serve. For example, Wordpress and Shopify accept strings with HTML tags as "content", so no parsing/adjustments are necessary.

-   [WordPress Resources](https://developer.wordpress.org/rest-api/reference/posts/#create-a-post)
    
-   [Shopify Resources](https://shopify.dev/docs/api/admin-rest/2023-04/resources/article#post-blogs-blog-id-articles)
    

* * *

## Getting Content Score for a specific URL

Using Audit endpoints, you can get Content Score for the URL you pick and up to 5 competitors we select automatically.

To do this:

1.  Create a new query via _POST_ request to _/api/v1/audits_ endpoint.
    
2.  Store "id" from our response:
    
    ```javascript
    {
        "state": "scheduled",
        "id": 767429
    }
    ```
    
3.  Set a timeout for a couple of minutes - with a fast-loading, audited page and regular Surfer traffic query, it should take 5-10 minutes.
    
4.  Send a _GET_ request using _/api/v1/audits/:id_ endpoint, here _/api/v1/audits/767429_  
    If "_state_" is still "_scheduled,_" rerun the _GET_ request again in a couple of minutes.
    
5.  In response, you should ultimately get:
    
    ```javascript
    {
    "state": "completed",
    "id": 482473,
    "competitors_pages": [
    {
    "url": "https://www.competitor1.com/",
    "content_score": 64
    },
    {
    "url": "https://www.competitor2.com/",
    "content_score": 49
    },
    {
    "url": "https://www.competitor3.com/",
    "content_score": 55
    },
    {
    "url": "https://www.competitor4.com/",
    "content_score": 78
    },
    {
    "url": "https://www.competitor5.com/",
    "content_score": 48
    }
    ],
    "audited_page": {
    "url": "https://www.auditedURL.com/",
    "content_score": 81
    }
    }
    ```
    
    Audited URL's Content Score is available under audited\_page.content\_score.
    

* * *

## Detecting AI content in a text

Use the AI Detector endpoint to estimate the probability that a given text was AI-generated. It returns an overall probability, the model used, and optional per-chunk details.

Sample cURL:

```javascript
curl -X POST "https://app.surferseo.com/api/v1/ai_detector/detect" \
  -H "Content-Type: application/json" \
  -H "API-KEY: YOUR_API_KEY" \
  -d '{
        "text": "Paste or load up to 100k characters here.",
        "max_chunk_size": 8190,
        "model": "surfer-ai-detector-v2",
        "semantic_chunking": true
      }'
```

Sample response:

```javascript
{
  "model": "surfer-ai-detector-v2",
  "ai_probability": 0.82,
  "chunks": [
    { "start": 0, "end": 1200, "probability": 0.76 },
    { "start": 1201, "end": 2400, "probability": 0.88 }
  ]
}
```

-   **Input:** `text` (≤100,000 chars). Optional: `max_chunk_size`, `model` (`surfer-ai-detector-v1` or `-v2`), `semantic_chunking` (default `true`).
    
-   **Errors you may see:** `422 Quota exceeded | No access`, `429 Rate limit exceeded`.
    
-   **Rate limit (endpoint):** 60 requests/min.
    

* * *

## Humanizing text (paraphrase to sound more natural)

Use the Humanizer endpoint to rewrite longer passages so they read more human-like while preserving meaning.

Sample cURL:

```javascript
curl -X POST "https://app.surferseo.com/api/v1/humanizer/humanize" \
  -H "Content-Type: application/json" \
  -H "API-KEY: YOUR_API_KEY" \
  -d '{
        "text": "Provide 128+ characters you want to humanize.",
        "model": "surfer-humanizer-v1",
        "stream": false
      }'
```

Sample response:

```javascript
{
  "model": "surfer-humanizer-v1",
  "text": "Here’s the rewritten version that keeps your meaning but reads more naturally."
}
```

-   **Input:** `text` (≥128 chars); `model`: `surfer-humanizer-v1`; optional `stream` for chunked output.
    
-   **Common error:** `422 Quota exceeded | No access`.
    

* * *

## ​Gathering data about SERP competitors for your SEO analysis

If you want to get statistical data about competitors from Google or export a list of prominent terms we discovered, you can take advantage of these endpoints:

-    _/api/v1/exports/csv/serp\_analyzer/:id/search\_results_ 
    
-    _/api/v1/exports/csv/serp\_analyzer/:id/prominent\_terms_ endpoints.
    

To do that, you can:

1.  Create SERP Analyzer queries for keywords you want to analyze using a _POST_ request to _/api/v1/serp\_analyzer_ or _/api/v1/serp\_analyzer/batches_ endpoints.
    
2.  Store the response "_id_" value of each query you're interested in.
    
    ```javascript
    {
    "state": "scheduled",
    "id": 2800997
    }
    ```
    
3.  Set a timeout for a couple of minutes - with regular Surfer traffic, a query should take 5-10 minutes.  
    If you ran more than 10 queries at once or in short succession, they might complete more slowly due to load-balancing done on our end.
    
4.  You can now run _GET_ requests:  
    \- to _/api/v1/exports/csv/serp\_analyzer/_2800997_/search\_results_ endpoint, to get a list of SERP competitors and numerical data regarding their ranked URLs, including Content Score  
    \- to _/api/v1/exports/csv/serp\_analyzer/_2800997_/prominent\_terms_ endpoint, to get a list of prominent terms we discovered within SERP results.  
    ​  
    Please note that these results are "raw data" and are not equal to what you'd see as Guidelines in Content Editor or Audit, which get additional processing.
    

## Additional resources:

[Surfer API Introduction](https://docs.surferseo.com/en/articles/5700335-surfer-api-introduction.md)

[Surfer API Documentation](https://app.surferseo.com/api/v1/docs#section/Introduction)

​[Surfer API Troubleshooting](https://docs.surferseo.com/en/articles/8196553-surfer-api-troubleshooting.md)