Werken aan Boord / Documentatie

De REST API.

Lees openbare gegevens zonder sleutel. Gebruik OAuth voor je eigen gegevens en schrijfopdrachten.

Basisadres

De API gebruikt JSON. Datums gebruiken YYYY-MM-DD. Tijdstempels gebruiken ISO 8601.

Voorbeeld

https://werkenaanboord.nl/v1

Volledig OpenAPI-contract met velden en schema’s Download API-uitleg

Vacatures zoeken

Voorbeeld

curl --fail-with-body --get "https://werkenaanboord.nl/v1/jobs" \
  --data-urlencode "role=schipper" \
  --data-urlencode "work_type=relief" \
  --data-urlencode "available_from=2026-10-01" \
  --data-urlencode "available_to=2026-10-31" \
  --data-urlencode "limit=5"

Filter	Betekenis
role	Functie of Nederlands synoniem uit /v1/taxonomy
work_type	permanent (vast) of relief (afloswerk)
available_from / available_to	Afloswerk moet binnen deze periode vallen. Vaste banen blijven mogelijk.
engagement	employee, freelance of either
sailing_area	Tekst in het vaargebied, bijvoorbeeld Rijn
certificate	Exact certificaat, bijvoorbeeld ADN
limit / cursor	1–100 resultaten; gebruik next_cursor voor de volgende pagina
updated_since	Alleen actieve vacatures die na dit tijdstip zijn gewijzigd

Het antwoord lezen

Lijsten gebruiken data, count en bij vacatures next_cursor. Eén record staat in data. Een lege lijst is een geldig resultaat.

Gebruik job_url voor de vacaturepagina en source_url voor de oorspronkelijke bron. Ontbrekende gegevens zijn geen bevestigde gegevens.

Voorbeeld

{
  "data": [],
  "count": 0,
  "query": { "role": "schipper", "limit": "5" },
  "next_cursor": null
}

JavaScript, Python en synchronisatie

Leesacties

Methode en pad	Resultaat
GET /taxonomy	Functies, synoniemen en vaste termen
GET /jobs	Actieve openbare vacatures
GET /jobs/{id-of-slug}	Eén actieve vacature
GET /availability	Beschikbaarheid die de hele gevraagde periode dekt; role, needed_from en needed_to zijn verplicht
GET /workers/{id-of-slug}	Openbaar profiel met beschikbaarheid
GET /me	Eigen records; login vereist
GET /watches/{id}/matches	Actuele matches voor een eigen zoekmelding; watches:write vereist

Authenticatie

Gebruik OAuth 2.1 Authorization Code met PKCE. Het resource-adres voor het token is https://werkenaanboord.nl/api/mcp, ook voor REST.

De server ondersteunt Client ID Metadata Documents (CIMD). Gebruik een client die dit ondersteunt. Dynamische clientregistratie staat niet aan.

De CLI regelt browserlogin en tokenvernieuwing. Een bestaand OAuth-token kan via WAB_TOKEN worden gebruikt.

Een browsersessie werkt op de eigen site. Schrijfverzoeken met een sessie vereisen een Origin-header die overeenkomt met de site.

Scope	Toegang
jobs:write	Eigen vacatures en werkgevercontrole
profile:write	Eigen profielen en beschikbaarheid
booking:write	Boekingsverzoeken
watches:write	Eigen zoekmeldingen

Inloggen met de CLI OAuth-metadata Resource-metadata

Een vacature voorbereiden

Maak vacature.json met de onderstaande voorbeeldvelden. Vervang de voorbeeldgegevens voor je een preview maakt.

Zet een geldig OAuth-token in WAB_TOKEN. Zet tokens nooit in een prompt of openbare broncode.

Voorbeeld

{
  "type": "relief",
  "role": "schipper",
  "employer_name": "Voorbeeldrederij",
  "start_date": "2026-10-12",
  "end_date": "2026-10-19",
  "sailing_area": "Rijn",
  "engagement": "freelance"
}

Download vacature.json

Vraag de preview op

Bewaar data.draft_id. Toon data.preview volledig en vraag akkoord. De preview-route vereist geen idempotentiesleutel.

Voorbeeld

curl --fail-with-body "https://werkenaanboord.nl/v1/jobs/preview" \
  -H "Authorization: Bearer $WAB_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @vacature.json

Publiceer de goedgekeurde draft

Een publicatie kan handmatige beoordeling krijgen. Controleer moderation_status voordat je zegt dat de vacature openbaar is.

Een sleutel bevat 8–200 tekens. Gebruik dezelfde sleutel en inhoud bij een retry. Gebruik een nieuwe sleutel voor een andere actie.

Voorbeeld

curl --fail-with-body "https://werkenaanboord.nl/v1/jobs" \
  -H "Authorization: Bearer $WAB_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: VERVANG-DOOR-EEN-UNIEKE-SLEUTEL" \
  --data '{"draft_id":"VERVANG-DOOR-DRAFT-ID"}'

Schrijfacties

Alle paden beginnen met /v1. Publicaties en wijzigingen vereisen een Idempotency-Key. Alleen preview-verzoeken zijn uitgezonderd.

Zoekmeldingen worden opgeslagen. Automatische e-mail- en webhookbezorging is nog niet beschikbaar. Gebruik geplande opvragingen voor meldingen.

Methode en pad	Doel
POST /jobs/preview → POST /jobs	Vacature voorbereiden en publiceren
PATCH /jobs/{id}	Velden wijzigen, of alleen status: active, paused of closed
DELETE /jobs/{id}	Vacature uit openbare resultaten verwijderen
POST /workers/availability/preview → POST /workers/availability	Profiel en eerste beschikbaarheid samen publiceren
PATCH /workers/{id} · DELETE /workers/{id}	Profiel beheren; verwijderen verwijdert ook gekoppelde gegevens
PATCH /availability/{id} · DELETE /availability/{id}	Eigen beschikbaarheid beheren
POST /booking-requests	Verzoek maken voor een volledig beschikbare periode
POST /watches · PATCH /watches/{id} · DELETE /watches/{id}	Zoekmelding bewaren en beheren
POST /employer-verifications	Zakelijk e-maildomein laten controleren

Fouten oplossen

Voorbeeld

{"error":{"code":"validation_error","issues":[{"field":"start_date","message":"Use YYYY-MM-DD."}]}}

HTTP	Actie
400	Controleer JSON en idempotentiesleutel
401	Log in of vernieuw het toegangstoken
403	Controleer scopes en bij browsersessies de Origin-header
404	Controleer de ID; het record kan privé, gesloten of van een ander account zijn
409	Controleer de draft, slug, sleutel of boekingsperiode
410	Bereid opnieuw voor en vraag opnieuw akkoord
413	Verklein de aanvraag tot maximaal 64 KB
422	Herstel de velden in error.issues
429	Wacht volgens Retry-After
500	Probeer later; behoud bij schrijven dezelfde sleutel en inhoud