API Scoutee : documentation développeur

L'API Scoutee donne accès en lecture à la base d'appels d'offres depuis vos propres outils : script de veille, CRM, tableau de bord interne. Elle expose deux points d'entrée, la recherche et le détail d'un avis, ainsi que les deux mêmes opérations sous forme de serveur MCP pour les assistants.

Base URL : https://scoutee.org/api

Toutes les réponses sont en JSON (application/json), en UTF-8. Les dates sont au format ISO 8601 (2026-09-05T14:30:00Z).

Clés API

Une clé appartient à un workspace, pas à une personne : elle survit au départ de celui qui l'a créée, et les administrateurs du workspace peuvent la révoquer à tout moment.

Une clé n'est créée et n'est utilisable que si le workspace est sur une offre payante — Standard, ou Beta. Si le workspace repasse sur l'offre gratuite, les clés existantes restent listées mais les appels répondent 403.

Pour créer une clé : page de votre workspace, section « API », bouton « Créer une clé ». La valeur complète n'est affichée qu'une fois, à la création. Scoutee n'en conserve que l'empreinte SHA-256 et ne peut donc pas vous la redonner ; en cas de perte, révoquez la clé et créez-en une nouvelle.

Format d'une clé : sct_ suivi de 40 caractères hexadécimaux. Les 12 premiers caractères (le préfixe, par exemple sct_1a2b3c4d) sont affichés dans la liste des clés pour vous permettre de les reconnaître.

Un workspace peut avoir 10 clés actives au maximum. Au-delà, la création répond 409 : révoquez une clé avant d'en créer une autre.

Authentification

Toutes les requêtes portent la clé dans l'en-tête X-API-Key :

curl -s "https://scoutee.org/api/tenders?page_size=5" \
  -H "X-API-Key: sct_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"

La clé est une identité de lecture seule : elle n'ouvre que GET /tenders et GET /tenders/{id}. Tout autre chemin répond 403, y compris les routes de gestion des clés elles-mêmes, qui exigent une session utilisateur.

La clé n'est jamais facultative. L'API n'a ni accès anonyme ni accès en offre gratuite : elle n'existe que pour les workspaces sur une offre payante. Une requête sans X-API-Key répond 401 {"detail": "Login required"}, et une clé inconnue ou révoquée répond 401 {"detail": "Clé API invalide"}.

Ne mettez jamais une clé dans du code exécuté par un navigateur ou dans un dépôt public : elle donne accès aux résultats complets que paie votre workspace.

Quotas

Chaque recherche consomme une unité de quota. Le compteur est tenu par clé : deux clés du même workspace ne se partagent pas le même seau. Le détail d'un avis (GET /tenders/{id}) ne consomme rien.

Il ne peut y avoir que ces deux lignes : une clé n'existe que sur une offre payante, et les deux offres payantes portent exactement les mêmes limites. Que votre workspace soit en Standard ou en Beta, une clé dispose de 10 000 recherches par heure, 240 par minute, 200 résultats par page et 500 pages au maximum. (Les limites plus serrées appliquées aux visiteurs et à l'offre gratuite ne concernent que la recherche du site : rien n'atteint l'API sans clé.)

Les valeurs demandées au-delà de ces plafonds ne sont pas une erreur : elles sont ramenées au plafond. page_size=500 renvoie 200 résultats, et le champ page_size de la réponse indique la valeur réellement appliquée.

Chaque réponse de recherche porte trois en-têtes :

GET /tenders

Recherche paginée. Par défaut : appels d'offres ouverts uniquement, du plus récent au plus ancien. Les avis publiés sur plusieurs portails sont dédupliqués : une seule ligne par avis, les autres portails apparaissant dans also_on.

Paramètres

Tous facultatifs, passés en query string.

Réponse

200 OK, objet TenderPage :

Un objet Tender :

Un objet AlsoOn : source_id (entier), source_name (chaîne), source_country (chaîne, nullable), url (chaîne).

Exemple

curl -s -G "https://scoutee.org/api/tenders" \
  -H "X-API-Key: $SCOUTEE_API_KEY" \
  --data-urlencode "keyword=voirie" \
  --data-urlencode "keyword=signalisation" \
  --data-urlencode "country=France" \
  --data-urlencode "sort=deadline" \
  --data-urlencode "page_size=50"

{
  "items": [
    {
      "id": 918233,
      "source_id": 12,
      "source_name": "PLACE",
      "source_country": "FR",
      "external_id": "25-114287",
      "title": "Travaux de voirie et de signalisation horizontale",
      "buyer": "Communauté de communes du Val de Loire",
      "description": "Marché à bons de commande pour la réfection de voirie...",
      "url": "https://www.marches-publics.gouv.fr/?page=Entreprise.EntrepriseAdvancedSearch&id=25-114287",
      "location": "Loiret",
      "procedure": "Procédure adaptée",
      "cpv_codes": ["45233220", "45233221"],
      "sectors": ["45"],
      "estimated_value": 420000.0,
      "currency": "EUR",
      "published_at": "2026-09-01T08:00:00Z",
      "deadline_at": "2026-10-03T12:00:00Z",
      "first_seen_at": "2026-09-01T09:12:44Z",
      "last_seen_at": "2026-09-05T06:03:11Z",
      "closed_at": null,
      "favorite": false,
      "also_on": []
    }
  ],
  "total": 137,
  "page": 1,
  "page_size": 50,
  "pages": 3,
  "by_country": { "France": 137, "Belgium": 12 },
  "by_sector": { "45": 96, "71": 28, "50": 13 }
}

En Python, avec requests :

import os
import requests

BASE = "https://scoutee.org/api"
HEADERS = {"X-API-Key": os.environ["SCOUTEE_API_KEY"]}

response = requests.get(
    f"{BASE}/tenders",
    headers=HEADERS,
    params={
        "keyword": ["voirie", "signalisation"],
        "country": ["France"],
        "sort": "deadline",
        "page_size": 50,
    },
    timeout=30,
)
response.raise_for_status()
page = response.json()

print(page["total"], "avis", "|", response.headers["X-Quota-Remaining"], "recherches restantes")
for tender in page["items"]:
    print(tender["id"], tender["deadline_at"], tender["title"])

Parcourir toutes les pages :

def iter_tenders(**params):
    """Toutes les pages d'une recherche, dans l'ordre demandé."""
    page = 1
    while True:
        response = requests.get(
            f"{BASE}/tenders",
            headers=HEADERS,
            params={**params, "page": page, "page_size": 200},
            timeout=30,
        )
        response.raise_for_status()
        body = response.json()
        yield from body["items"]
        if page >= body["pages"]:
            return
        page += 1

Pour une veille incrémentale, gardez la date du dernier passage et repassez-la en seen_after : seuls les avis découverts depuis reviennent.

GET /tenders/{id}

Un avis, enrichi comme un résultat de recherche. Ne consomme pas de quota.

curl -s "https://scoutee.org/api/tenders/918233" \
  -H "X-API-Key: $SCOUTEE_API_KEY"

La réponse est un objet Tender, identique à ceux de items. Si l'identifiant demandé désigne la copie d'un avis publié sur plusieurs portails, c'est la copie de référence qui est renvoyée. Un identifiant inconnu répond 404.

Serveur MCP

Les deux mêmes opérations sont exposées sous forme de serveur MCP : un assistant — Claude Code, Cursor, VS Code, Windsurf, ou tout autre client du protocole — peut ainsi chercher des appels d'offres pour vous sans que vous écriviez une ligne de HTTP.

• URL : https://scoutee.org/api/mcp
• Transport : Streamable HTTP, sans session, réponses JSON (aucun flux à maintenir ouvert, donc compatible avec n'importe quel proxy)
• Authentification : la même clé de workspace, dans X-API-Key ou dans Authorization: Bearer, et tout aussi obligatoire — un appel sans clé revient en erreur d'outil réclamant une clé
• Quotas : identiques au REST — 10 000 recherches par heure sur l'une comme sur l'autre offre payante, une unité par appel à search_tenders, rien pour get_tender, comptées dans le même seau par clé

Outils

search_tenders reprend les paramètres de GET /tenders, avec la même sémantique : q, keyword (tableau), country (tableau), source_id, min_value, max_value, sort (newest, oldest, deadline), include_closed, seen_after, page et page_size. Tous facultatifs. page_size vaut 20 par défaut plutôt que 50, un avis étant un objet volumineux à donner à un modèle, et reste plafonné à 200. Le résultat est un TenderPage augmenté de trois champs qui portent ce que portent les en-têtes de quota en HTTP : quota_plan, quota_limit et quota_remaining.

get_tender prend un seul tender_id et renvoie le même objet Tender que GET /tenders/{id}. Il ne consomme pas de quota.

Claude Code

claude mcp add --transport http scoutee https://scoutee.org/api/mcp \
  --header "X-API-Key: sct_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"

Cursor, VS Code, Windsurf et les autres clients

La plupart lisent un fichier de configuration contenant un objet mcpServers (.cursor/mcp.json, .vscode/mcp.json, ~/.codeium/windsurf/mcp_config.json…) :

{
  "mcpServers": {
    "scoutee": {
      "url": "https://scoutee.org/api/mcp",
      "headers": {
        "X-API-Key": "sct_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
      }
    }
  }
}

Python

Avec le paquet mcp (pip install mcp) :

import asyncio
import os

import httpx2
from mcp.client import Client
from mcp.client.streamable_http import streamable_http_client

URL = "https://scoutee.org/api/mcp"


async def main():
    headers = {"X-API-Key": os.environ["SCOUTEE_API_KEY"]}
    async with httpx2.AsyncClient(headers=headers) as http:
        async with Client(streamable_http_client(URL, http_client=http)) as client:
            print([tool.name for tool in (await client.list_tools()).tools])
            result = await client.call_tool(
                "search_tenders",
                {"keyword": ["voirie"], "country": ["France"], "page_size": 10},
            )
            page = result.structured_content
            print(page["total"], "avis |", page["quota_remaining"], "recherches restantes")
            for tender in page["items"]:
                print(tender["id"], tender["deadline_at"], tender["title"])


asyncio.run(main())

Un appel en échec revient avec is_error positionné et le message anglais qu'aurait renvoyé l'API REST, suivi de son code stable entre crochets (Invalid API key [invalid_api_key]) : clé inconnue, quota épuisé, identifiant introuvable. Les codes sont ceux de la section Erreurs ci-dessous.

Erreurs

Le corps d'une erreur est toujours {"detail": "..."}, et le message est toujours en anglais, quelle que soit la langue de votre intégration : l'anglais est la langue de travail de l'API. Chaque erreur qu'un utilisateur peut rencontrer porte aussi un code stable dans l'en-tête de réponse X-Error-Code : votre intégration s'appuie sur ce code et rédige son propre message, plutôt que de comparer le texte.

Une réponse quota_exceeded répète ses nombres dans X-Error-Limit (recherches par heure) et X-Error-Minutes (l'attente) : le message peut ainsi être reconstruit dans n'importe quelle langue.

Les réponses 429 portent un en-tête Retry-After, en secondes. Respectez-le plutôt que de réessayer immédiatement :

import time

def search(**params):
    """Une recherche, avec attente si le quota par minute est atteint."""
    for _ in range(3):
        response = requests.get(f"{BASE}/tenders", headers=HEADERS, params=params, timeout=30)
        if response.status_code != 429:
            response.raise_for_status()
            return response.json()
        time.sleep(int(response.headers.get("Retry-After", "60")))
    raise RuntimeError("quota toujours épuisé après trois tentatives")

Les codes 402 et 403 ne se corrigent pas en réessayant : vérifiez l'offre du workspace, ou créez une nouvelle clé si la vôtre a été révoquée.

En MCP, les mêmes échecs reviennent sous forme d'erreurs d'outil portant les mêmes messages, et non de codes HTTP.