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`	Your Discover projects and their details.
`write:products`	Ask for changes to your Discover projects: page drafts, screenshots, Briefs, review replies, lead status. What happens depends on the mode you set per project: a proposal you apply (Manual), a draft edit (Hybrid), or a public post (Autonomous). Your page itself still changes only after Woodander editors approve the draft.
`read:analytics`	Views, clicks, referrers and leads of your projects, and the synced Google Analytics (GA4) figures of your sites.
`read:seo`	Your sites, synced Search Console data and site audits.
`read:media`	Your Woodander Media articles, posts for your site and Content Studio drafts.
`read:gtm`	Your Google Tag Manager containers, tags, triggers and variables, tracking analysis and site scans.
`write:gtm`	Ask for Tag Manager changes. What happens depends on the mode you set per site: a proposal you apply (Manual) or a change in the separate Woodander workspace (Hybrid). Publishing still waits for your confirmation.
`publish:gtm`	Make Tag Manager versions live without asking you, only where you turned on Autonomous. Give it only to an agent you trust.
`read:keywords`	Keyword ideas with search volume, competition and CPC (each new lookup uses one of your plan’s daily keyword lookups), your tracked keywords and their ranking history.
`write:media`	Create and edit your private Media drafts. Woodander editors still review every piece; sending a draft to them stays yours. What happens depends on the mode you set for Media in Settings → AI activity.
`run:audits`	Start site audits and refresh the Search Console and Google Analytics data of your sites, within your plan’s limits. What happens depends on the mode you set for SEO.
`read:autopilot`	The pieces Content Autopilot wrote that wait for your review.
`write:autopilot`	Approve (publish) or discard pieces waiting for your review. What happens depends on the mode you set for Content Autopilot; discarding always waits for you.
`read:market`	Your Market listings and their status.
`write:market`	Add draft listings, edit and pause your Market listings; sending them to editors stays yours. What happens depends on the mode you set for Market.
`read:content`	The approved articles for your own site, for a site connected through the Woodander API to pull.
`write:content`	Tell Woodander where your site published an approved article (its address and 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.