Scoutee API: developer documentation

The Scoutee API gives read access to the tender database from your own tools: a monitoring script, a CRM, an internal dashboard. It exposes two endpoints, the search and a single notice, and the same two operations as an MCP server for assistants.

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

Every response is JSON (application/json), UTF-8. Dates are ISO 8601 (2026-09-05T14:30:00Z).

API keys

A key belongs to a workspace, not to a person: it outlives whoever created it, and the workspace administrators can revoke it at any time.

A key can only be created, and only works, while the workspace is on a paid plan — Standard, or Beta. If the workspace goes back to the free plan, the existing keys stay listed but calls answer 403.

To create a key: your workspace page, section "API", button "Create a key". The full value is shown once, at creation. Scoutee only stores its SHA-256 digest and cannot show it to you again; if you lose it, revoke the key and create another one.

Key format: sct_ followed by 40 hexadecimal characters. The first 12 characters (the prefix, for example sct_1a2b3c4d) are shown in the key list so that you can recognise a key.

A workspace can hold at most 10 active keys. Beyond that, creation answers 409: revoke a key before creating another one.

Authentication

Every request carries the key in the X-API-Key header:

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

A key is a read-only credential: it opens GET /tenders and GET /tenders/{id}, nothing else. Any other path answers 403, including the key management routes themselves, which require a signed-in session.

The key is never optional. The API has no anonymous access and no free-plan access: it exists only for workspaces on a paid plan. A request without X-API-Key answers 401 {"detail": "Login required"}, and a key that is unknown or revoked answers 401 {"detail": "Clé API invalide"}.

Never put a key in code that runs in a browser, or in a public repository: it opens the complete search results your workspace pays for.

Quotas

Each search consumes one quota unit. The counter is kept per key: two keys of the same workspace do not share one bucket. Fetching a single notice (GET /tenders/{id}) consumes nothing.

These are the only two rows there can be: a key only exists on a paid plan, and both paid plans carry exactly the same limits. Whichever of Standard or Beta your workspace is on, a key gets 10,000 searches per hour, 240 per minute, 200 results per page and 500 pages at most. (The tighter limits the website applies to visitors and to the free plan are a matter for the site's own search; nothing reaches the API without a key.)

Asking for more than these caps is not an error: the value is clamped. page_size=500 returns 200 results, and the page_size field of the response reports the value actually applied.

Every search response carries three headers:

GET /tenders

Paginated search. By default: open tenders only, newest first. Notices published on several portals are deduplicated: one row per notice, the other portals appearing in also_on.

Parameters

All optional, passed in the query string.

Response

200 OK, a TenderPage object:

A Tender object:

An AlsoOn object: source_id (integer), source_name (string), source_country (string, nullable), url (string).

Example

curl -s -G "https://scoutee.org/api/tenders" \
  -H "X-API-Key: $SCOUTEE_API_KEY" \
  --data-urlencode "keyword=roadworks" \
  --data-urlencode "keyword=signage" \
  --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 }
}

Notices are returned in the language they were published in: the API does not translate them.

In Python, with 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": ["roadworks", "signage"],
        "country": ["France"],
        "sort": "deadline",
        "page_size": 50,
    },
    timeout=30,
)
response.raise_for_status()
page = response.json()

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

Walking every page:

def iter_tenders(**params):
    """Every page of a search, in the requested order."""
    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

For incremental monitoring, keep the timestamp of your last run and pass it back as seen_after: only the notices discovered since then come back.

GET /tenders/{id}

One notice, enriched like a search result. Consumes no quota.

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

The response is a Tender object, identical to those of items. If the requested identifier points at the copy of a notice published on several portals, the canonical copy is returned. An unknown identifier answers 404.

MCP server

The same two operations are exposed as an MCP server, so an assistant — Claude Code, Cursor, VS Code, Windsurf, or anything else that speaks the protocol — can search tenders on your behalf without you writing a line of HTTP.

• URL: https://scoutee.org/api/mcp
• Transport: Streamable HTTP, stateless, JSON responses (no stream to hold open, so it works through any proxy)
• Authentication: the same workspace key, in X-API-Key or in Authorization: Bearer, and just as mandatory — a call without one comes back as a tool error asking for a key
• Quotas: identical to REST — 10,000 searches an hour on either paid plan, one unit per search_tenders call, nothing for get_tender, counted in the same per-key bucket

Tools

search_tenders takes the query parameters of GET /tenders, with the same semantics: q, keyword (array), country (array), source_id, min_value, max_value, sort (newest, oldest, deadline), include_closed, seen_after, page and page_size. All optional. page_size defaults to 20 rather than 50, since a notice is a large object to hand to a model, and is still capped at 200. The result is a TenderPage plus three fields that carry what the quota headers carry over HTTP: quota_plan, quota_limit and quota_remaining.

get_tender takes a single tender_id and returns the same Tender object as GET /tenders/{id}. It consumes no quota.

Claude Code

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

Cursor, VS Code, Windsurf and other clients

Most of them read a config file holding an mcpServers object (.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

With the mcp package (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": ["roadworks"], "country": ["France"], "page_size": 10},
            )
            page = result.structured_content
            print(page["total"], "notices |", page["quota_remaining"], "searches left")
            for tender in page["items"]:
                print(tender["id"], tender["deadline_at"], tender["title"])


asyncio.run(main())

A call that fails comes back with is_error set and the English message the REST API would have answered with, followed by its stable code in brackets (Invalid API key [invalid_api_key]): an unknown key, an exhausted quota, an unknown identifier. The codes are those of the Errors section below.

Errors

An error body is always {"detail": "..."}, and the message is always in English, whatever the language of your integration: English is the working language of the API. Every error a user can meet also carries a stable code in the X-Error-Code response header, so your integration can branch on the code and write its own message instead of matching on the text.

A quota_exceeded answer repeats its numbers in X-Error-Limit (searches an hour) and X-Error-Minutes (the wait), so a message can be rebuilt in any language.

A 429 carries a Retry-After header, in seconds. Honour it rather than retrying at once:

import time

def search(**params):
    """One search, waiting out the per-minute quota when it is hit."""
    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 still exhausted after three attempts")

402 and 403 are not fixed by retrying: check the plan of the workspace, or create a new key if yours was revoked.

Over MCP the same failures come back as tool errors carrying the same messages, rather than as HTTP status codes.