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`	Tus proyectos de Discover y sus detalles.
`write:products`	Pedir cambios en tus proyectos de Discover: borradores de la página, capturas, breves, respuestas a reseñas, estado de los leads. Lo que pasa depende del modo de cada proyecto: una propuesta que aplicas (Manual), un cambio en el borrador (Híbrido) o una publicación (Autónomo). Tu página solo cambia cuando los editores de Woodander aprueban el borrador.
`read:analytics`	Vistas, clics, referencias y leads de sus proyectos, y las cifras sincronizadas de Google Analytics (GA4) de sus sitios.
`read:seo`	Tus sitios, datos sincronizados de Search Console y auditorías de sitios.
`read:media`	Tus artículos de Woodander Media, entradas para tu sitio y borradores de Content Studio.
`read:gtm`	Tus contenedores, etiquetas, activadores y variables de Google Tag Manager, análisis de seguimiento y escaneos de sitios.
`write:gtm`	Pide cambios en Tag Manager. Lo que ocurre depende del modo que fijes por sitio: una propuesta que tú aplicas (Manual) o un cambio en el espacio de trabajo independiente de Woodander (Híbrido). La publicación sigue esperando tu confirmación.
`publish:gtm`	Activar versiones de Tag Manager sin preguntarte, solo donde activaste «Autónomo». Dáselo únicamente a un agente de confianza.
`read:keywords`	Ideas de palabras clave con volumen de búsqueda, competencia y CPC (cada búsqueda nueva usa una de las búsquedas diarias de tu plan), tus palabras clave seguidas y su historial de posiciones.
`write:media`	Crear y editar tus borradores privados de Media. Los editores de Woodander siguen revisando cada pieza; enviarles un borrador sigue siendo cosa tuya. Lo que ocurre depende del modo de Media en Ajustes → Actividad de IA.
`run:audits`	Iniciar auditorías y actualizar los datos de Search Console y Google Analytics de tus sitios, dentro de los límites de tu plan. Lo que ocurre depende del modo que fijes para SEO.
`read:autopilot`	Las piezas que escribió Content Autopilot y esperan tu revisión.
`write:autopilot`	Aprobar (publicar) o descartar piezas que esperan tu revisión. Lo que ocurre depende del modo de Content Autopilot; descartar siempre espera tu confirmación.
`read:market`	Tus anuncios de Market y su estado.
`write:market`	Añadir borradores de anuncios, editar y pausar tus anuncios de Market; enviarlos a los editores sigue siendo cosa tuya. Lo que ocurre depende del modo que fijes para Market.
`read:content`	Los artículos aprobados para tu propio sitio, que un sitio conectado a través de la API de Woodander descarga por su cuenta.
`write:content`	Informar a Woodander de dónde publicó tu sitio un artículo aprobado (su dirección e 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.