Woodander API reference

Every REST endpoint and the MCP tool with the same name, generated from the live API catalog. Version 1, JSON over HTTPS.

Get started

API and MCP access is included in the Pro and Scale plans. See plans.
In the Workspace open Settings, API & MCP, choose what the token may read and an expiry, and create it. The token is shown once.
Send it as a Bearer token to https://woodander.com/api/v1.

bash

curl -H "Authorization: Bearer wdr_..." https://woodander.com/api/v1/whoami

A machine-readable description is at https://woodander.com/api/v1/openapi.json (OpenAPI 3.1). The MCP server is at https://woodander.com/mcp; set it up in the guides.

Authentication

Personal access tokens (wdr_...) are sent as Authorization: Bearer <token>. A token belongs to one person and sees only that person's data. It is stored hashed, so we cannot show it again; if you lose it, revoke it and create another.

A missing, malformed, expired or revoked token gets 401. A token without the scope an endpoint needs gets 403 with insufficient_scope. If the plan no longer includes API access the answer is 403 with plan_required.

Scopes

Scope	Grants
`read:products`	Ihre Discover-Projekte und deren Details.
`write:products`	Änderungen an Ihren Discover-Projekten anfragen: Seitenentwürfe, Screenshots, Kurzmeldungen, Antworten auf Bewertungen, Lead-Status. Was passiert, hängt vom Modus pro Projekt ab: ein Vorschlag, den Sie anwenden (Manuell), eine Entwurfsänderung (Hybrid) oder eine öffentliche Veröffentlichung (Autonom). Ihre Seite selbst ändert sich erst, wenn die Woodander-Redaktion den Entwurf freigibt.
`read:analytics`	Aufrufe, Klicks, Verweise und Leads Ihrer Projekte sowie die synchronisierten Google-Analytics-Zahlen (GA4) Ihrer Websites.
`read:seo`	Ihre Websites, synchronisierte Search-Console-Daten und Website-Audits.
`read:media`	Ihre Woodander-Media-Artikel, Beiträge für Ihre Website und Content-Studio-Entwürfe.
`read:gtm`	Ihre Google-Tag-Manager-Container, Tags, Trigger und Variablen, Tracking-Analyse und Website-Scans.
`write:gtm`	Bitten Sie um Änderungen in Tag Manager. Was dann geschieht, hängt vom Modus ab, den Sie pro Website festlegen: ein Vorschlag, den Sie anwenden (Manuell), oder eine Änderung im separaten Woodander-Workspace (Hybrid). Das Veröffentlichen wartet weiterhin auf Ihre Bestätigung.
`publish:gtm`	Tag-Manager-Versionen ohne Rückfrage live schalten, nur dort, wo Sie „Autonom“ aktiviert haben. Geben Sie dies nur einem Agenten, dem Sie vertrauen.
`read:keywords`	Keyword-Ideen mit Suchvolumen, Wettbewerb und CPC (jede neue Abfrage verbraucht eine der täglichen Keyword-Abfragen Ihres Tarifs), Ihre verfolgten Keywords und ihr Ranking-Verlauf.
`write:media`	Private Media-Entwürfe anlegen und bearbeiten. Die Woodander-Redaktion prüft weiterhin jeden Beitrag; das Einsenden bleibt bei dir. Was passiert, hängt vom Modus für Media unter Einstellungen → KI-Aktivität ab.
`run:audits`	Website-Audits starten und die Search-Console- und Google-Analytics-Daten deiner Websites aktualisieren, im Rahmen deines Tarifs. Was passiert, hängt vom Modus ab, den du für SEO festlegst.
`read:autopilot`	Die Texte, die Content Autopilot geschrieben hat und die auf deine Prüfung warten.
`write:autopilot`	Texte, die auf deine Prüfung warten, freigeben (veröffentlichen) oder verwerfen. Was passiert, hängt vom Modus für Content Autopilot ab; Verwerfen wartet immer auf dich.
`read:market`	Deine Market-Inserate und ihr Status.
`write:market`	Entwürfe für Inserate anlegen, deine Market-Inserate bearbeiten und pausieren; das Einsenden an die Redaktion bleibt bei dir. Was passiert, hängt vom Modus ab, den du für Market festlegst.
`read:content`	Die freigegebenen Artikel für Ihre eigene Website, die eine über die Woodander-API verbundene Website selbst abruft.
`write:content`	Woodander mitteilen, wo Ihre Website einen freigegebenen Artikel veröffentlicht hat (Adresse und ID).

Rate limits

60 requests per minute per token, on REST and MCP together, and 20 Tag Manager changes per minute per token. Over the limit you get 429 with error.code = rate_limited and a Retry-After header (seconds).

Errors

Every error has the same shape. Match on error.code; the message is for people.

json

{"error": {"code": "not_found", "message": "Site was not found."}}

HTTP	Code	Meaning
401	`unauthenticated`	Missing, invalid, expired or revoked token.
403	`insufficient_scope`	The token does not have the scope this endpoint needs.
403	`plan_required`	The owner's plan does not include API access.
404	`not_found`	Not found, or not yours. Other people's data is indistinguishable from missing data.
404	`search_console_not_connected`	The site has no connected Search Console property.
404	`gtm_container_not_chosen`	No Tag Manager container is chosen for the site.
409	`busy`	Another request of the same account is using its allowance: try again in a moment.
409	`google_reconnect`	Google no longer accepts the owner's Tag Manager access: they reconnect in the Workspace.
409	`duplicate`	The change would duplicate a tag, trigger or variable the container already has (or the version is already live).
422	`invalid_request`	A parameter is not valid (range, type, cursor).
422	`validation_failed`	The body of a change is not valid; details.errors names the fields.
429	`rate_limited`	Too many requests. See Retry-After.
429	`limit_reached`	The plan's daily keyword lookups are used up; the message says when they reset (see whoami limits).
429	`account_spend_cap`	The account reached this month's keyword data limit.
502	`provider_error`	The keyword data provider failed; nothing was spent. Try again later.
503	`provider_not_connected`	Keyword data is not connected on this server yet.
503	`provider_budget_reached`	Keyword data is paused until the next month.

Pagination and shapes

Responses are {"data": ..., "meta": ...} with stable field names and ISO 8601 dates. Lists take limit and cursor: pass meta.next_cursor back as cursor until it is null. Cursors are opaque.