Skip to content
Woodander Docs
EN

Media

Your Media articles and article drafts.

4 endpoints. Each one is a REST endpoint under https://woodander.com/api/v1 and an MCP tool with the same name and arguments. See the overview for authentication, rate limits and errors.

list_articles

GET /api/v1/articles

Your written pieces: Woodander Media articles, posts for your own site and Content Studio drafts, newest first.

MCP tool list_articles Scope read:media Plan Pro and above

Parameters

NameInTypeRequiredDescription
status query string No Keep one status, e.g. draft, in_review, published.
type query string No Keep one kind. One of: media, site_post, seo_content.
limit query integer No Page size, 1 to 100.
cursor query string No meta.next_cursor of the previous page.

Example request

bash
curl "https://woodander.com/api/v1/articles" \
  -H "Authorization: Bearer wdr_..."
tools/call
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "list_articles",
        "arguments": {}
    }
}

Example response Example

json
{
    "data": [
        {
            "id": "media-12",
            "type": "media",
            "title": "How we ship",
            "status": "published",
            "excerpt": "Short.",
            "locale": "en",
            "slug": "how-we-ship",
            "url": "https://woodander.com/media/how-we-ship",
            "is_sponsored": false,
            "product": null,
            "site": null,
            "published_at": "2026-10-01T08:00:00+00:00",
            "updated_at": "2026-10-02T08:00:00+00:00"
        }
    ],
    "meta": {
        "next_cursor": null,
        "limit": 25,
        "total": 1,
        "status": null,
        "type": null
    }
}

Errors

HTTPCodeMeaning
401unauthenticatedMissing, invalid, expired or revoked token.
403insufficient_scopeThe token does not have the read:media scope.
403plan_requiredThe plan does not include API access.
422invalid_requestA parameter is not valid (range, type, cursor).
429rate_limitedToo many requests. See the Retry-After header.

get_article

GET /api/v1/articles/{id}

One article with its Markdown body (the latest working draft while it is being edited).

MCP tool get_article Scope read:media Plan Pro and above

Parameters

NameInTypeRequiredDescription
id path string Yes Article id such as media-12, site_post-5 or seo_content-3 (see list_articles).

Example request

bash
curl "https://woodander.com/api/v1/articles/12" \
  -H "Authorization: Bearer wdr_..."
tools/call
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get_article",
        "arguments": {
            "id": 12
        }
    }
}

Example response Example

json
{
    "data": {
        "id": "media-12",
        "type": "media",
        "title": "How we ship",
        "status": "draft",
        "body_markdown": "# Heading\n\nText."
    }
}

Errors

HTTPCodeMeaning
401unauthenticatedMissing, invalid, expired or revoked token.
403insufficient_scopeThe token does not have the read:media scope.
403plan_requiredThe plan does not include API access.
404not_foundNot found, or not yours.
429rate_limitedToo many requests. See the Retry-After header.

create_article_draft

POST /api/v1/articles/drafts

Create a private Media draft from Markdown in your name. It stays private: sending it to Woodander editors (with your rights statement) is yours in the editor, editors review every piece, and paid labels are never touched. Drafts an agent wrote are marked AI-assisted. What happens depends on the mode the owner set for this module in Settings → AI activity: Manual stores a proposal the owner applies in the Workspace (the answer has a confirm_url), Hybrid and Autonomous run it. Poll agent_change_status with the id.

MCP tool create_article_draft Scope write:media Plan Pro and above

Parameters

NameInTypeRequiredDescription
title body string Yes Title, up to 160 characters.
excerpt body string No Teaser, up to 300 characters.
body_markdown body string Yes The body in Markdown (headings, lists, links, images by https address). Unsafe markup is removed.
locale body string Yes Language code of the piece, e.g. en or uk.
type body string No Format of the piece (default story).
topic_id body integer No A Media topic id.
related_product_id body integer No One of your Discover projects the piece is about.

Example request

bash
curl -X POST "https://woodander.com/api/v1/articles/drafts" \
  -H "Authorization: Bearer wdr_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"example","body_markdown":"example","locale":"example"}'
tools/call
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "create_article_draft",
        "arguments": {
            "title": "example",
            "body_markdown": "example",
            "locale": "example"
        }
    }
}

Example response Example

json
{
    "data": {
        "id": 41,
        "action": "media.create_draft",
        "risk": "reversible",
        "status": "done",
        "needs": null,
        "summary": "Create the draft “Notes on a quiet launch”",
        "diff": [
            {
                "op": "+",
                "kind": "Title",
                "name": "",
                "details": [
                    "Language: en"
                ],
                "before": null,
                "after": "Notes on a quiet launch"
            }
        ],
        "requested_by": "Token “Claude Code”",
        "note": null,
        "error": null,
        "result": {
            "summary": "Draft saved. It is private until you send it to Woodander editors from the editor.",
            "article_id": "media-12",
            "editor_url": "https://woodander.com/media/edit/12"
        },
        "confirm_url": null,
        "created_at": "2026-10-19T09:00:00+00:00",
        "decided_at": null
    },
    "meta": {
        "outcome": "done",
        "module": "media",
        "mode": "hybrid",
        "hint": null
    }
}

Errors

HTTPCodeMeaning
401unauthenticatedMissing, invalid, expired or revoked token.
403insufficient_scopeThe token does not have the write:media scope.
403plan_requiredThe plan does not include API access.
422validation_failedThe body is not valid; details.errors names the fields.
429rate_limitedToo many requests. See the Retry-After header.

update_article_draft

PATCH /api/v1/articles/drafts/{id}

Change the title, teaser or Markdown body of the working draft of one of your Media pieces. What is with the editors or published stays as it is until you send the draft again. Fields you send replace those fields. What happens depends on the mode the owner set for this module in Settings → AI activity: Manual stores a proposal the owner applies in the Workspace (the answer has a confirm_url), Hybrid and Autonomous run it. Poll agent_change_status with the id.

MCP tool update_article_draft Scope write:media Plan Pro and above

Parameters

NameInTypeRequiredDescription
id path string Yes Id of one of your Media drafts, e.g. media-12 (see list_articles).
title body string No Title, up to 160 characters.
excerpt body string No Teaser, up to 300 characters.
body_markdown body string No The body in Markdown (headings, lists, links, images by https address). Unsafe markup is removed.

Example request

bash
curl -X PATCH "https://woodander.com/api/v1/articles/drafts/12" \
  -H "Authorization: Bearer wdr_..."
tools/call
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "update_article_draft",
        "arguments": {
            "id": 12
        }
    }
}

Example response Example

json
{
    "data": {
        "id": 41,
        "action": "media.update_draft",
        "risk": "reversible",
        "status": "pending",
        "needs": "apply",
        "summary": "Update the draft “Notes on a quiet launch” (title)",
        "diff": [
            {
                "op": "~",
                "kind": "Title",
                "name": "",
                "details": [],
                "before": "Notes on a quiet launch",
                "after": "Notes on a calm launch"
            }
        ],
        "requested_by": "Token “Claude Code”",
        "note": null,
        "error": null,
        "result": null,
        "confirm_url": "https://woodander.com/workspace/settings/ai-activity?module=media&change=41",
        "created_at": "2026-10-19T09:00:00+00:00",
        "decided_at": null
    },
    "meta": {
        "outcome": "proposed",
        "module": "media",
        "mode": "manual",
        "hint": null
    }
}

Errors

HTTPCodeMeaning
401unauthenticatedMissing, invalid, expired or revoked token.
403insufficient_scopeThe token does not have the write:media scope.
403plan_requiredThe plan does not include API access.
404not_foundNot found, or not yours.
422validation_failedThe body is not valid; details.errors names the fields.
429rate_limitedToo many requests. See the Retry-After header.