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 — Pro or Team (a legacy paid workspace keeps Pro and Team limits respectively). 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": "Invalid API key"}.

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.

A key only exists on a paid plan, so these are the only rows there can be. The two legacy paid plans are not sold any more and are not listed: they carry Pro's and Team's limits respectively. (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 at https://scoutee.org/api/mcp, with the same key, the same parameters and the same quotas, so Claude Code, Cursor, VS Code, Windsurf or any client of the protocol can search tenders on your behalf. Setup, tools and examples are on the MCP server page.

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.