Blogs API

Retrieve, publish, and manage AI-generated blog content. All endpoints are under /api/v1/blogs.

Naming convention: REST API responses use camelCase field names (e.g. htmlContent). Webhook payloads use snake_case(e.g. html_content).

GET/api/v1/blogs

List published blogs with pagination, category filter, and search.

Auth: API Key (X-Api-Key)

Parameters

Name	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`pageSize`	integer	No	Items per page (default: 12, max: 50)
`category`	string	No	Filter by category
`search`	string	No	Search in title and meta description
`sort`	string	No	"newest" (default), "oldest", or "title"

Response

{
  "blogs": [
    {
      "title": "10 Web Design Trends for 2026",
      "slug": "10-web-design-trends-2026",
      "metaDescription": "Discover the latest...",
      "excerpt": "A short summary of the blog post...",
      "featuredImageUrl": "/api/v1/blogs/images/{id}/banner.webp",
      "category": "Web Design",
      "readingTimeMinutes": 8,
      "wordCount": 3500,
      "keywords": ["web design", "trends", "2026"],
      "publishedAt": "2026-01-29T10:00:00Z"
    }
  ],
  "totalCount": 42,
  "page": 1,
  "pageSize": 12,
  "totalPages": 4
}

GET/api/v1/blogs/{slug}

Get a single blog by slug. Returns full HTML content, CSS, JavaScript, and SEO metadata.

Auth: API Key (X-Api-Key)

Parameters

Name	Type	Required	Description
`slug`	string	Yes	Blog URL slug

Response

{
  "title": "10 Web Design Trends for 2026",
  "slug": "10-web-design-trends-2026",
  "htmlContent": "<article>...</article>",
  "cssContent": "body { ... }",
  "jsContent": "...",
  "metaDescription": "Discover the latest...",
  "schemaOrgJson": "{...}",
  "featuredImageUrl": "/api/v1/blogs/images/{id}/banner.webp",
  "ogImageUrl": "/api/v1/blogs/images/{id}/og.webp",
  "keywords": ["web design", "trends", "2026"],
  "readingTimeMinutes": 8,
  "wordCount": 3500,
  "publishedAt": "2026-01-29T10:00:00Z",
  "category": "Web Design"
}

GET/api/v1/blogs/{slug}/related

Get related blog posts (up to 3) based on category and keywords. Returns a flat array (same item shape as the list endpoint).

Auth: API Key (X-Api-Key)

Parameters

Name	Type	Required	Description
`slug`	string	Yes	Blog URL slug
`limit`	integer	No	Max related posts (default: 3, max: 10)

Response

[
  {
    "title": "Modern CSS Techniques",
    "slug": "modern-css-techniques",
    "metaDescription": "...",
    "excerpt": "...",
    "featuredImageUrl": "/api/v1/blogs/images/{id}/banner.webp",
    "category": "Web Design",
    "readingTimeMinutes": 6,
    "wordCount": 2200,
    "keywords": ["css", "web design"],
    "publishedAt": "2026-01-20T10:00:00Z"
  }
]

GET/api/v1/blogs/categories

Get all blog categories with post counts. Returns a flat array (not wrapped in an object).

Auth: API Key (X-Api-Key)

Response

[
  { "category": "Web Design", "count": 12 },
  { "category": "SEO", "count": 8 },
  { "category": "eCommerce", "count": 5 }
]

POST/api/v1/blogs/{blogId}/publish

Publish a blog. Generates a URL slug and sets status to Published. Triggers an automatic visual quality check in the background. Returns the full blog object (same shape as GET /api/v1/blogs/{slug}).

Auth: API Key (X-Api-Key, blogs:write scope)

Parameters

Name	Type	Required	Description
`blogId`	UUID	Yes	Blog ID
`customSlug`	string	No	Custom URL slug (auto-generated from title if omitted)

Response

{
  "title": "10 Web Design Trends for 2026",
  "slug": "10-web-design-trends-2026",
  "htmlContent": "<article>...</article>",
  "publishedAt": "2026-01-29T10:00:00Z"
}

PUT/api/v1/blogs/{blogId}

Update a published blog. Supports partial updates — only include fields you want to change. Returns the full updated blog object (same shape as GET /api/v1/blogs/{slug}).

Auth: API Key (X-Api-Key, blogs:write scope)

Parameters

Name	Type	Required	Description
`blogId`	UUID	Yes	Blog ID
`title`	string	No	Updated title
`htmlContent`	string	No	Updated HTML content
`cssContent`	string	No	Updated CSS
`jsContent`	string	No	Updated JavaScript
`metaDescription`	string	No	Updated meta description
`category`	string	No	Updated category
`keywords`	string[]	No	Updated keywords

Response

{
  "title": "10 Web Design Trends for 2026",
  "slug": "10-web-design-trends-2026",
  "htmlContent": "<article>...</article>",
  "cssContent": "...",
  "metaDescription": "...",
  "category": "Web Design",
  "publishedAt": "2026-01-29T10:00:00Z"
}

POST/api/v1/blogs/{blogId}/visual-check

Trigger an AI visual quality check. Takes desktop and mobile screenshots, analyzes for layout issues, broken images, duplicate TOC, and more.

Auth: API Key (X-Api-Key, blogs:write scope)

Parameters

Name	Type	Required	Description
`blogId`	UUID	Yes	Blog ID
`url`	string	No	URL to check (defaults to published URL)

Response

{
  "success": true,
  "blogId": "...",
  "overallScore": 85,
  "issues": [
    {
      "severity": "warning",
      "category": "toc",
      "description": "Duplicate table of contents detected",
      "suggestion": "Remove the blog's built-in TOC"
    }
  ],
  "reasoning": "Good overall layout with minor TOC issue",
  "autoFixApplied": false,
  "checkedUrl": "https://yoursite.com/blog/your-post"
}

GET/api/v1/blogs/{blogId}/visual-check

Get the latest visual check results for a blog (up to 5 most recent checks).

Auth: API Key (X-Api-Key)

Parameters

Name	Type	Required	Description
`blogId`	UUID	Yes	Blog ID

Response

{
  "success": true,
  "blogId": "...",
  "checks": [
    {
      "id": "...",
      "overallScore": 85,
      "issues": "[...]",
      "aiReasoning": "Good overall layout",
      "autoFixApplied": false,
      "checkedUrl": "https://...",
      "createdAt": "2026-01-29T10:05:00Z"
    }
  ]
}

Image URLs are always relative. Fields like featuredImageUrl and ogImageUrl return paths like /api/v1/blogs/images/{id}/banner.webp. Always prefix them with your WUDO API base URL (e.g. https://wudoseo.com) when rendering absolute URLs for meta tags, sitemaps, or external references. Image URLs inside htmlContent are also relative and follow the same pattern.

Error Codes

Status	Meaning
`200`	Success
`401`	Invalid or missing API key
`403`	Feature not available on your plan
`404`	Blog not found
`429`	Rate limit exceeded