Hoe het werkt

De standaardmodus: typ wat je zoekt in gewone woorden en krijg advertenties en veilingkavels terug.

1. Typ in de zoekbalk, bijvoorbeeld:
   gezellige fauteuil voor onder de €100
2. Verfijn met Filters: bron (Tweedehands, Veiling of Kringloop), minimum- en maximumprijs, en postcode met straal voor dingen in de buurt.
3. Tip: klik op het foto-icoontje om met een afbeelding te zoeken in plaats van woorden.
4. Wissel tussen Resultaten (lijst) en Kaarten, en blader met Vorige en Volgende.
5. Zie je iets interessants? Klik erop — de advertentie opent in een nieuw tabblad. Met vergelijkbaar bij een resultaat vind je meer van hetzelfde. Klik op het bladwijzer-icoontje om een koopje te bewaren (account nodig) — alles terug te vinden onder Bewaard bovenaan de resultaten.

Semantisch + keyword zoeken over de hele index. Auth: Authorization: Bearer kk_…. Limiet (Gratis): 60/minuut, 100/dag — meer via Abonnement.

curl -s "https://koopje.ai/v1/search?q=vintage+stoel&price_max=200&limit=5" \
  -H "Authorization: Bearer $KOOPJE_API_KEY"

Verdieping nodig? GET /v1/similar?url=… vindt gelijkende advertenties, GET /v1/contents?urls=… (max 20) haalt volledige details op. Volledige referentie: API-referentie.

Kies de modus Agent (slotje: hiervoor heb je een gratis account nodig). De agent zoekt niet één keer, maar werkt je vraag stap voor stap af — en je ziet live wat hij doet.

1. Stel je vraag en kijk mee terwijl de agent meerdere zoekslagen uitvoert.
2. Vraag gerust door in hetzelfde gesprek — hij onthoudt waar jullie het over hadden.
3. Klaar voor iets nieuws? Klik op Gesprek wissen en begin opnieuw.

De website-agent als API: hij voert zelf meerdere zoekslagen uit en stuurt het antwoord als Server-Sent Events stream. Stuur JSON met message (verplicht), plus conversation (lijst met eerdere berichten voor vervolgvragen), source (exacte site of veilinghuis), listing_type (tweedehands, veiling, kringloop) en/of category (een van de 27 slugs). Limiet (Gratis): 10/minuut, 10/dag — meer via Abonnement.

curl -N -X POST "https://koopje.ai/v1/agent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KOOPJE_API_KEY" \
  -d '{"message": "zoek een racefiets voor een beginner, max 500 euro"}'

Liever zelf de keten bouwen? Combineer /v1/search → /v1/contents — precies wat onze skill doet (Eigen AI koppelen).

Maak een account (en eventueel een API key)

Voor de ChatGPT-app en de OAuth-koppeling heb je geen API key nodig: de app opent zelf een login- en toestemmingsscherm. Voor Claude, Codex, Gemini, OpenClaw en n8n gebruik je wel een persoonlijke API key:

1. Maak een gratis account en log in.
2. Open Mijn profiel → MCP & API keys → Nieuwe sleutel.
3. Kopieer de code (begint met kk_…). Je ziet hem maar één keer, dus bewaar hem meteen.

Gratis en fair use: normaal zoeken kan volop, de uitgebreide AI-antwoorden maximaal een paar keer per minuut. Kom je eroverheen, dan zegt hij dat er gewoon bij — er gaat niets stuk.

Kies je assistent

Installeer de koopje.ai-zoekskill, zodat je tweedehands advertenties en veilingkavels in België kunt doorzoeken.

1. Download https://koopje.ai/skill/koopje-search/SKILL.md en https://koopje.ai/skill/koopje-search/references/api.md
2. Bewaar ze als een skill met het API-referentiebestand in een references-submap, op de standaard skills-locatie van je platform (OpenClaw: ~/.openclaw/workspace/skills/koopje-search/ — Hermes: ~/.hermes/skills/web/koopje-search/).
3. Vraag me om mijn KOOPJE_API_KEY (begint met kk_) als je die nog niet hebt, en test de verbinding met GET https://koopje.ai/v1/stats en header Authorization: Bearer <mijn API key>.
4. Bevestig in één zin wat je installeerde en hoeveel er te doorzoeken valt (total uit /v1/stats).

mkdir -p ~/.openclaw/workspace/skills/koopje-search/references
curl -s -o ~/.openclaw/workspace/skills/koopje-search/SKILL.md \
  https://koopje.ai/skill/koopje-search/SKILL.md
curl -s -o ~/.openclaw/workspace/skills/koopje-search/references/api.md \
  https://koopje.ai/skill/koopje-search/references/api.md
export KOOPJE_API_KEY="kk_plak_hier_je_key"

mkdir -p ~/.hermes/skills/web/koopje-search/references
curl -s -o ~/.hermes/skills/web/koopje-search/SKILL.md \
  https://koopje.ai/skill/koopje-search/SKILL.md
curl -s -o ~/.hermes/skills/web/koopje-search/references/api.md \
  https://koopje.ai/skill/koopje-search/references/api.md
export KOOPJE_API_KEY="kk_plak_hier_je_key"

{
  mcp: {
    servers: {
      koopje: {
        url: "https://koopje.ai/mcp",
        transport: "streamable-http",
        headers: { Authorization: "Bearer kk_plak_hier_je_key" }
      }
    }
  }
}

mcp_servers:
  koopje:
    url: "https://koopje.ai/mcp"
    headers:
      Authorization: "Bearer kk_plak_hier_je_key"

Installeer de koopje.ai-zoekskill, zodat je tweedehands advertenties en veilingkavels in België kunt doorzoeken.

1. Download https://koopje.ai/skill/koopje-search/SKILL.md en https://koopje.ai/skill/koopje-search/references/api.md
2. Bewaar ze als een skill met het API-referentiebestand in een references-submap, op je standaard skills-locatie (~/.claude/skills/koopje-search/).
3. Vraag me om mijn KOOPJE_API_KEY (begint met kk_) als je die nog niet hebt, en test de verbinding met GET https://koopje.ai/v1/stats en header Authorization: Bearer <mijn API key>.
4. Bevestig in één zin wat je installeerde en hoeveel er te doorzoeken valt (total uit /v1/stats).

mkdir -p ~/.claude/skills/koopje-search/references
curl -s -o ~/.claude/skills/koopje-search/SKILL.md \
  https://koopje.ai/skill/koopje-search/SKILL.md
curl -s -o ~/.claude/skills/koopje-search/references/api.md \
  https://koopje.ai/skill/koopje-search/references/api.md
export KOOPJE_API_KEY="kk_plak_hier_je_key"

claude mcp add --transport http koopje https://koopje.ai/mcp \
  --header "Authorization: Bearer kk_plak_hier_je_key"

{
  "mcpServers": {
    "koopje": {
      "type": "http",
      "url": "https://koopje.ai/mcp",
      "headers": { "Authorization": "Bearer kk_plak_hier_je_key" }
    }
  }
}

export KOOPJE_API_KEY="kk_plak_hier_je_key"
codex mcp add koopje --url https://koopje.ai/mcp --bearer-token-env-var=KOOPJE_API_KEY

Installeer de koopje.ai-zoekskill, zodat je tweedehands advertenties en veilingkavels in België kunt doorzoeken.

1. Download https://koopje.ai/skill/koopje-search/SKILL.md en https://koopje.ai/skill/koopje-search/references/api.md
2. Bewaar ze als een skill met het API-referentiebestand in een references-submap, op je standaard skills-locatie.
3. Vraag me om mijn KOOPJE_API_KEY (begint met kk_) als je die nog niet hebt, en test de verbinding met GET https://koopje.ai/v1/stats en header Authorization: Bearer <mijn API key>.
4. Bevestig in één zin wat je installeerde en hoeveel er te doorzoeken valt (total uit /v1/stats).

{
  "mcpServers": {
    "koopje": {
      "httpUrl": "https://koopje.ai/mcp",
      "headers": { "Authorization": "Bearer kk_plak_hier_je_key" }
    }
  }
}

Stel een proefvraag

Is alles gelukt? Stel je assistent dan bijvoorbeeld deze vraag:

Krijg je advertenties terug met een prijs, een plaats en een link? Dan werkt alles. Vraag daarna gerust door — je assistent onthoudt het gesprek.

Dezelfde index als de REST API, maar als hosted MCP-server (JSON-RPC 2.0 over Streamable HTTP) — voor Claude, Cursor, ChatGPT, Codex, Gemini en elke andere MCP-client. Auth met dezelfde Bearer kk_… key als de REST API; zelfde limieten en quota. Zonder key werkt zoeken ook — dan geldt 30/minuut + 50/dag per IP-adres (zo werkt de ChatGPT-directory). Met een gratis account of API key wordt dat 60/minuut + 100/dag. Bewaarde zoekertjes, herinneringen en je profiel vereisen een login: een API key of een OAuth-koppeling via de ChatGPT-app. Je kunt een koppeling intrekken onder Mijn profiel → MCP & API keys → Gekoppelde apps.

Stap-voor-stap per assistent (ChatGPT, Claude, Codex, Gemini, OpenClaw/Hermes, n8n) staat in Eigen AI koppelen.

Zoeken werkt zonder login. De bewaar-, *_reminder- en get_profile-tools blijven zichtbaar, maar vragen zonder login om je koopje.ai-account te koppelen (OAuth) of om een API key mee te sturen. Bewaarde zoekertjes en herinneringen zijn ook te beheren onder Mijn profiel.

Generieke config (werkt voor Cursor, VS Code, OpenCode en de meeste MCP-clients — ~/.cursor/mcp.json):

{
  "mcpServers": {
    "koopje": {
      "url": "https://koopje.ai/mcp",
      "headers": { "Authorization": "Bearer kk_..." }
    }
  }
}

Of test de server direct met curl — eerst de handshake, dan een zoekopdracht:

curl -X POST "https://koopje.ai/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer kk_..." \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

curl -X POST "https://koopje.ai/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer kk_..." \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_listings","arguments":{"q":"racefiets","limit":5}}}'

Identiek aan de REST API per key (Gratis): search, similar, contents en stats 60/minuut + 100/dag; de agent-tool 10/minuut + 10/dag. Hogere limieten via Abonnement. Zonder key: 30/minuut + 50/dag per IP-adres; met een gratis account of API key 60/minuut + 100/dag. Zelfde foutcodes — zie API-referentie.

Authenticatie

Elke aanvraag naar /v1/* vereist een Bearer token. Maak een API key via de zijbalk (MCP & API keys, na aanmelden) en stuur die als header mee.

curl "https://koopje.ai/v1/search?q=fiets&limit=5" \
  -H "Authorization: Bearer kk_a1b2c3d4..."

Formaat: API keys beginnen altijd met kk_ gevolgd door 32 willekeurige tekens. Ze zijn eenmalig zichtbaar bij het aanmaken — bewaar ze veilig.

Zoeken

Semantisch zoeken over de hele index. Ondersteunt automatisch, semantisch of keyword matchen; prijs- en bron-filters; sorteren op relevantie. Het antwoord bevat hasMore — true zolang er een volgende pagina is (blader met offset).

Voor korte product- en modelvragen doet de server eerst een lexicale must-match-controle. matchType is dan exact, close, related of none; bij een ruimere match staan notice en relaxedTerms in het antwoord. Presenteer zulke resultaten niet als exacte treffers.

Bij een daglimiet krijg je HTTP 429 met plan, quota (limiet, gebruikt, reset) en upgrade_url. GET /v1/me toont dezelfde quota-info plus het verbruik van vandaag.

curl "https://koopje.ai/v1/search?q=vintage+stoel&price_max=200&limit=5" \
  -H "Authorization: Bearer kk_..."

{
  "requestId": "…",
  "resolvedSearchType": "auto",
  "matchType": "exact",
  "resolvedCategory": "computers",
  "resolvedCategoryLabel": "Computers en software",
  "resolvedCategorySource": "auto",
  "searchTime": 84.2,
  "costDollars": { "total": 0 },
  "results": [
    { "title": "…", "price_value": 75, "source": "2dehands", … }
  ]
}

Gelijkaardige koopjes

curl "https://koopje.ai/v1/similar?url=https%3A%2F%2Fwww.2dehands.be%2Fv%2F..." \
  -H "Authorization: Bearer kk_..."

Agent

curl -N -X POST "https://koopje.ai/v1/agent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer kk_..." \
  -d '{"message": "zoek een racefiets voor een beginner, max 500 euro"}'

Inhoud ophalen

Stats

curl "https://koopje.ai/v1/stats" \
  -H "Authorization: Bearer kk_..."

Bewaard

curl -X POST "https://koopje.ai/v1/saved" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer kk_..." \
  -d '{"url": "https://www.2dehands.be/v/…", "title": "Racefiets", "price_text": "€350"}'

Herinneringen

curl -X POST "https://koopje.ai/v1/alerts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer kk_..." \
  -d '{"query_text": "vintage racefiets onder 300 euro", "price_max": 300, "frequency": "weekly"}'

Fouten

De API gebruikt gewone HTTP-statuscodes en een JSON-body met {"error": "..."}.

Versiebeleid

/v1/ is stabiel: bestaande velden verdwijnen niet en bestaande limieten gaan niet omlaag zonder aankondiging. Nieuwe velden en endpoints kunnen zonder versiesprong bijkomen — controleer daarom nooit op exacte responses, alleen op de velden die je gebruikt.

Elke /v1/-respons draagt RateLimit-Limit, RateLimit-Remaining en RateLimit-Reset (seconden), plus RateLimit-Policy met de per-minute- en per-day-buckets. Antwoorden met 429 hebben bovendien Retry-After — wacht dat aantal seconden en probeer opnieuw.

Breaking changes komen als /v2/ met minimaal 6 maanden overlap, aangekondigd op deze pagina en per mail naar API-gebruikers.