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`	Ваші проєкти в Discover та їхні деталі.
`write:products`	Запитувати зміни ваших проєктів у Discover: чернетки сторінки, знімки, новини, відповіді на відгуки, статус лідів. Що станеться, залежить від режиму проєкту: пропозиція, яку ви застосовуєте («Вручну»), правка чернетки («Гібрид») або публікація («Автономно»). Сама сторінка змінюється лише після схвалення чернетки редакторами Woodander.
`read:analytics`	Перегляди, кліки, джерела переходів і ліди ваших проєктів та синхронізовані показники Google Analytics (GA4) ваших сайтів.
`read:seo`	Ваші сайти, синхронізовані дані Search Console та аудити сайтів.
`read:media`	Ваші статті Woodander Media, дописи для вашого сайту та чернетки Content Studio.
`read:gtm`	Ваші контейнери, теги, тригери та змінні Google Tag Manager, аналіз відстеження та сканування сайтів.
`write:gtm`	Запитуйте зміни в Tag Manager. Що станеться, залежить від режиму, який ви задали для кожного сайту: пропозиція, яку ви застосовуєте (Вручну), або зміна в окремому робочому просторі Woodander (Гібридний). Публікація все одно чекає на ваше підтвердження.
`publish:gtm`	Робити версії Tag Manager активними без вашого запиту, лише там, де ви ввімкнули режим «Автономний». Надавайте це лише агенту, якому довіряєте.
`read:keywords`	Ідеї ключових слів з обсягом пошуку, конкуренцією та CPC (кожен новий пошук використовує один із щоденних пошуків вашого тарифу), ваші відстежувані ключові слова та історія їхніх позицій.
`write:media`	Створюйте та редагуйте свої приватні чернетки Media. Редактори Woodander все одно перевіряють кожен матеріал; надсилання чернетки їм лишається за вами. Результат залежить від режиму Media в Налаштування → Активність ШІ.
`run:audits`	Запускайте аудити сайтів та оновлюйте дані Search Console і Google Analytics ваших сайтів у межах вашого тарифу. Результат залежить від режиму, який ви задали для SEO.
`read:autopilot`	Матеріали, які написав Content Autopilot і які чекають вашої перевірки.
`write:autopilot`	Схвалюйте (публікуйте) або відхиляйте матеріали, що чекають вашої перевірки. Результат залежить від режиму Content Autopilot; відхилення завжди чекає на вас.
`read:market`	Ваші оголошення в Market та їхній статус.
`write:market`	Додавайте чернетки оголошень, редагуйте та призупиняйте свої оголошення в Market; надсилання редакторам лишається за вами. Результат залежить від режиму, який ви задали для Market.
`read:content`	Схвалені статті для вашого власного сайту, які сайт, підключений через API Woodander, забирає сам.
`write:content`	Повідомити Woodander, де ваш сайт опублікував схвалену статтю (її адреса та 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.