--- title: "Exemples d'utilisation de l'API Surfer" description: "Quelques exemples de notre API en action !" url: https://docs.surferseo.com/fr/articles/8201326-exemples-d-utilisation-de-l-api-surfer collection: "API" updated: 2026-10-26 language: fr alternates: [en, de] --- # Exemples d'utilisation de l'API Surfer Quelques exemples de notre API en action ! > **Warning:** Attention : ces exemples utilisent les endpoints v1. La v1 fonctionne toujours, mais elle est obsolète. Si vous créez une nouvelle intégration, utilisez plutôt les chemins v2 ci-dessous : ## **Correspondance des endpoints V1 → V2 :**

Ce que vous faites	V1 (obsolète)	V2 (recommandé)
Créer un Content Editor	`POST /api/v1/content_editors`	`POST /api/v2/workspaces/{workspace_id}/content_editors`
Obtenir le statut d'un Content Editor	`GET /api/v1/content_editors/{id}`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{id}`
Obtenir le contenu d'un Content Editor	`GET /api/v1/content_editors/{id}/content`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{id}/content`
Obtenir les termes NLP	`GET /api/v1/content_editors/{id}/terms`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{id}/seo_guidelines/terms`
Obtenir le Content Score	`GET /api/v1/content_editors/{id}/content_score`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{id}/seo_guidelines/score`
Lister les Content Editors	`GET /api/v1/content_editors`	`GET /api/v2/content_editors` ou `GET /api/v2/workspaces/{workspace_id}/content_editors`
Lister les espaces de travail	`GET /api/v1/workspaces`	`GET /api/v2/workspaces`

SERP Analyzer, Audit, AI Detector et Humanizer restent en V1 : les équivalents V2 ne sont pas encore disponibles pour ces outils. * * * Voici quelques flux de travail qui peuvent bénéficier de l'intégration de l'API Surfer via votre application personnalisée ou des solutions tierces comme Zapier ou Bubble.io : ## Créer plusieurs requêtes et partager des liens d'accès Via l'API, vous pouvez automatiser la création de requêtes pour Content Editor, Audit et SERP Analyzer. Ensuite, en fonction de nos réponses, vous pouvez créer des liens d'accès à l'application web. Par exemple, vous pourriez avoir une Google Sheet avec une liste de mots-clés pour lesquels vous souhaitez vous positionner, et vous voulez créer de nouveaux articles en utilisant Content Editor. Dans ce cas, vous pourriez : 1. Structurez votre feuille pour que chaque ligne contienne les mots-clés à cibler et la localisation de votre audience cible. 2. Pour chaque ligne, extrayez les mots-clés et les données de localisation et envoyez-les à l'aide d'une requête _POST_ vers l’endpoint _/api/v1/content\_editors_. _Conseil : N'oubliez pas que les mots-clés doivent toujours être un tableau,_ même si vous n'optimisez que pour un seul mot-clé. 3. En réponse, vous recevrez : ```javascript { "state": "scheduled", "permalink_hash": "kKi7n3pkRk7Gw5cxKDiBAbCAybnDTt2z", "id": 5632898 } ``` Vous pouvez maintenant créer des liens d'accès aux requêtes en : - joignant "[_https://app.surferseo.com/drafts/_](https://app.surferseo.com/drafts/)_" +_ « 5632898 » : cela crée un lien privé que le propriétaire du compte ou un membre de l'organisation peut consulter - joignant _"_[_https://app.surferseo.com/drafts/s/_](https://app.surferseo.com/drafts/s/)_" + "kKi7n3pkRk7Gw5cxKDiBA"_ créera un lien de partage public accessible à tous. 4. Partagez-les avec votre équipe et les rédacteurs externes, ou collez-les dans la feuille d'origine que vous avez utilisée pour la saisie des mots-clés : selon le flux de travail que vous préférez. * * * ## Publier du contenu écrit sur votre CMS Via l'API, vous pouvez obtenir une version HTML propre de votre brouillon Content Editor. Vous pouvez ensuite l'envoyer à Google Docs ou à votre CMS via une intégration personnalisée. Pour obtenir le contenu de la requête Editor, il vous suffit de : 1. Repérez l'« id » de la requête Content Editor à partir de laquelle vous souhaitez télécharger du contenu. _Conseil : Si vous n'avez pas stocké l'ID de la requête quelque part, trouvez-le simplement via l'application web et copiez le dernier_ [_https://app.surferseo.com/drafts/_](https://app.surferseo.com/drafts/)_5632898_ 2. Envoyez une requête _GET_ à _/api/v1/content\_editors/:id/content_ en spécifiant l'"id" que vous avez trouvé, ici _/api/v1/content\_editors/5632898/content_ 3. Stockez la réponse. Selon votre éditeur de texte/CMS cible, vous devrez peut-être analyser le HTML que nous fournissons. Par exemple, Wordpress et Shopify acceptent les chaînes avec des balises HTML en tant que « contenu », donc aucune analyse/ajustement n'est nécessaire. - [Ressources WordPress](https://developer.wordpress.org/rest-api/reference/posts/#create-a-post) - [Ressources Shopify](https://shopify.dev/docs/api/admin-rest/2023-04/resources/article#post-blogs-blog-id-articles) * * * ## Obtenir le Content Score pour une URL spécifique À l'aide des endpoints Audit, vous pouvez obtenir le Content Score de l'URL que vous choisissez et de jusqu'à 5 concurrents que nous sélectionnons automatiquement. Pour ce faire : 1. Créez une nouvelle requête via _POST_ vers l’endpoint _/api/v1/audits_. 2. Stockez l'"id" de notre réponse : ```javascript { "state": "scheduled", "id": 767429 } ``` 3. Prévoyez un délai de quelques minutes : avec une page auditée à chargement rapide et une requête de trafic Surfer régulier, cela devrait prendre 5 à 10 minutes. 4. Envoyez une requête _GET_ en utilisant l’endpoint _/api/v1/audits/:id_, ici _/api/v1/audits/767429_ Si l'"_state_" est toujours "_scheduled,_" relancez la requête _GET_ à nouveau dans quelques minutes. 5. En réponse, vous devriez finalement obtenir : ```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 } } ``` Le Content Score de l'URL auditée est disponible sous audited\_page.content\_score. * * * ## Détecter le contenu généré par l'IA dans un texte Utilisez l’endpoint AI Detector pour estimer la probabilité qu'un texte donné ait été généré par l'IA. il renvoie une probabilité globale, le modèle utilisé et, en option, des détails par segment (chunk). Exemple 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 }' ``` Exemple de réponse : ```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 } ] } ``` - **Entrée :** `text` (≤100 000 caractères). Optionnel : `max_chunk_size`, `model` (`surfer-ai-detector-v1` ou `-v2`), `semantic_chunking` (par défaut `true`). - **Erreurs possibles :** `422 Quota exceeded | No access`, `429 Rate limit exceeded`. - **Limite de débit (endpoint) :** 60 requêtes/min. * * * ## Humaniser le texte (paraphraser pour un ton plus naturel) Utilisez l'endpoint Humanizer pour réécrire des passages plus longs afin qu'ils paraissent plus naturels tout en préservant le sens. Exemple 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 }' ``` Exemple de réponse : ```javascript { "model": "surfer-humanizer-v1", "text": "Voici la version réécrite qui conserve votre sens mais se lit plus naturellement." } ``` - **Entrée :** `text` (≥128 caractères) ; `model` : `surfer-humanizer-v1` ; `stream` optionnel pour une sortie fragmentée. - **Erreur courante :** `422 Quota exceeded | No access`. * * * ## Collecter des données sur les concurrents SERP pour votre analyse SEO Si vous souhaitez obtenir des données statistiques sur les concurrents de Google ou exporter une liste des termes importants que nous avons découverts, vous pouvez utiliser ces endpoints : - _/api/v1/exports/csv/serp\_analyzer/:id/search\_results_ - _/api/v1/exports/csv/serp\_analyzer/:id/prominent\_terms_ endpoints. Pour ce faire, vous pouvez : 1. Créez des requêtes SERP Analyzer pour les mots-clés que vous souhaitez analyser en utilisant une requête _POST_ vers les endpoints _/api/v1/serp\_analyzer_ ou _/api/v1/serp\_analyzer/batches_. 2. Conservez la valeur "_id_" de la réponse pour chaque requête qui vous intéresse. ```javascript { "state": "scheduled", "id": 2800997 } ``` 3. Prévoyez un délai de quelques minutes : avec le trafic Surfer habituel, une requête devrait prendre 5 à 10 minutes. Si vous avez lancé plus de 10 requêtes à la fois ou en succession rapide, elles pourraient se terminer plus lentement en raison de l'équilibrage de charge effectué de notre côté. 4. Vous pouvez maintenant exécuter des requêtes _GET_ : \- vers l’endpoint _/api/v1/exports/csv/serp\_analyzer/_2800997_/search\_results_ pour obtenir une liste des concurrents SERP et des données chiffrées sur leurs URL positionnées, y compris le Content Score \- vers l’endpoint _/api/v1/exports/csv/serp\_analyzer/_2800997_/prominent\_terms_ pour obtenir une liste des termes importants que nous avons découverts dans les résultats SERP. Veuillez noter que ces résultats sont des « données brutes » et ne correspondent pas aux Directives affichées dans le Content Editor ou l'Audit, qui font l'objet d'un traitement supplémentaire. ## Ressources supplémentaires : [Introduction à l'API Surfer](https://docs.surferseo.com/en/articles/5700335-surfer-api-introduction.md) [Documentation de l'API Surfer](https://app.surferseo.com/api/v1/docs#section/Introduction) [Dépannage de l'API Surfer](https://docs.surferseo.com/en/articles/8196553-surfer-api-troubleshooting.md)