Blogs API

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

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 content

Response

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

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.

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)

Response

{
  "blogs": [
    {
      "title": "Modern CSS Techniques",
      "slug": "modern-css-techniques",
      "metaDescription": "...",
      "category": "Web Design",
      "publishedAt": "2026-01-20T10:00:00Z"
    }
  ]
}

GET/api/v1/blogs/categories

Get all blog categories with post counts.

Auth: API Key (X-Api-Key)

Response

{
  "categories": [
    { "name": "Web Design", "count": 12 },
    { "name": "SEO", "count": 8 },
    { "name": "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.

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. AI automatically validates and fixes broken links.

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

Parameters

Name	Type	Required	Description
`blogId`	UUID	Yes	Blog ID
`htmlContent`	string	No	Updated HTML content
`cssContent`	string	No	Updated CSS
`metaDescription`	string	No	Updated meta description

Response

{
  "title": "10 Web Design Trends for 2026",
  "slug": "10-web-design-trends-2026",
  "updatedAt": "2026-01-29T12: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",
  "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