Posts

Posts are the core content of your blog - the very reason Waldium exists is so you can create, manage, and publish high-quality blog posts. On this page, we will dive into the different post endpoints you can use to manage posts programmatically. We will look at how to create, generate, retrieve, publish, and delete posts.

POST/v1/posts

Create a post

This endpoint allows you to create a new blog post with custom content. You can create posts with your own content, metadata, and formatting.

Required attributes

Name
title
Type
string
Description
The title of the blog post.

Optional attributes

Name
description
Type
string
Description
Brief description of the post.
Name
content
Type
string
Description
Main body of the post (Markdown supported).
Name
category
Type
string
Description
Post category.
Name
tags
Type
array
Description
Array of tags.
Name
authorId
Type
string
Description
Author's ID.
Name
isDraft
Type
boolean
Description
Post status: true for draft, false for published.

Request

POST

/v1/posts

curl -X POST https://api.waldium.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Getting Started with Blogging",
    "description": "A beginner'\''s guide to blogging",
    "content": "# Getting Started with Blogging\n\nBlogging is a great way to share your thoughts...",
    "category": "Technology",
    "tags": ["blogging", "beginner", "guide"],
    "isDraft": true
  }'

Response

{
  "success": true,
  "data": {
    "message": "Post created successfully",
    "post": {
      "id": "9c166d00-0921-406c-9b68-8409710223e2",
      "slug": "getting-started-with-blogging",
      "title": "Getting Started with Blogging",
      "description": "A beginner's guide to blogging",
      "category": "Technology",
      "tags": ["blogging", "beginner", "guide"],
      "authorId": null,
      "isDraft": true,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    "site": {
      "id": "site_123",
      "name": "Your Site Name"
    }
  }
}

POST/v1/posts/generate

Generate a post

This endpoint allows you to generate an AI-powered blog post using your knowledge base. This creates high-quality, contextual content based on your uploaded knowledge and specified parameters.

Required attributes

Name
topic
Type
string
Description
The topic for the blog post.

Optional attributes

Name
style
Type
string
Description
Writing style: "professional", "casual", "technical", "creative", "academic".
Name
length
Type
string
Description
Post length: "short", "medium", "long".
Name
tone
Type
string
Description
Writing tone: "informative", "persuasive", "conversational", "authoritative".
Name
includeExamples
Type
boolean
Description
Whether to include examples in the content.
Name
targetAudience
Type
string
Description
Target audience for the content.

Request

POST

/v1/posts/generate

curl -X POST https://api.waldium.com/api/v1/posts/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "The Future of AI in Content Marketing",
    "style": "professional",
    "length": "medium",
    "tone": "informative",
    "includeExamples": true,
    "targetAudience": "marketing professionals"
  }'

Response

{
  "message": "Post generated successfully",
  "post": {
    "id": "post_123",
    "slug": "future-of-ai-content-marketing",
    "title": "The Future of AI in Content Marketing",
    "description": "Short summary...",
    "category": "Technology",
    "tags": ["AI", "Marketing"],
    "authorId": "auth_123",
    "isDraft": false,
    "createdAt": "2025-08-08T04:32:21.956Z",
    "updatedAt": "2025-08-08T04:32:21.956Z"
  },
  "site": {
    "id": "site_123",
    "name": "Your Site Name"
  },
  "timestamp": "2025-08-08T04:32:21.956Z",
  "api": {
    "version": "v1",
    "status": "active"
  }
}

POST/v1/posts/batch

Batch generate posts

Schedule multiple posts to be generated at specific times. Use automatic distribution (provide startDate and endDate) or explicit scheduling (provide scheduledFor per post). Tasks are created and processed independently by a cron job.

Required attributes

Name
posts
Type
array
Description
Array of posts to generate (maximum 100 per batch).
- Name
  topic
  Type
  string
  Description
  The topic for the blog post.

Scheduling options (choose one)

Name
Option 1: Automatic Distribution
Description
Provide startDate and endDate at the root level. Posts will be evenly distributed between these times.
- Name
  startDate
  Type
  string
  Description
  ISO 8601 datetime when to start the campaign.
- Name
  endDate
  Type
  string
  Description
  ISO 8601 datetime when to end the campaign.
Name
Option 2: Explicit Scheduling
Description
Provide scheduledFor on each post for full control over timing.
- Name
  scheduledFor
  Type
  string
  Description
  ISO 8601 datetime when this specific post should be generated (per post).

Optional default attributes

Name
defaults
Type
object
Description
Default values applied to all posts unless overridden.
- Name
  authorId
  Type
  string
  Description
  Default author for posts.
- Name
  category
  Type
  string
  Description
  Default category.
- Name
  tags
  Type
  array
  Description
  Default tags array.
- Name
  status
  Type
  string
  Description
  Target status: DRAFT, UNLISTED, or PUBLISHED. Default is DRAFT.
- Name
  style
  Type
  string
  Description
  Writing style (professional, casual, technical).
- Name
  length
  Type
  string
  Description
  Post length (short, medium, long).
- Name
  tone
  Type
  string
  Description
  Writing tone (informative, conversational, formal).
- Name
  includeExamples
  Type
  boolean
  Description
  Whether to include examples.
- Name
  targetAudience
  Type
  string
  Description
  Target audience description.
- Name
  useKnowledge
  Type
  boolean
  Description
  Whether to use knowledge base.
- Name
  selectedFileIds
  Type
  array
  Description
  Knowledge file IDs to reference.
- Name
  model
  Type
  string
  Description
  AI model to use for generation.

Per-post attributes

Each post in the posts array can override any default value by including the same property.

Request

POST

/v1/posts/batch

curl -X POST https://api.waldium.com/api/v1/posts/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2025-01-20T14:00:00Z",
    "endDate": "2025-01-20T19:00:00Z",
    "defaults": {
      "category": "Technology",
      "tags": ["AI", "Tutorial"],
      "tone": "professional",
      "status": "PUBLISHED"
    },
    "posts": [
      { "topic": "Introduction to Machine Learning" },
      { "topic": "Understanding Neural Networks" },
      { "topic": "Natural Language Processing Basics" }
    ]
  }'

Response

{
  "success": true,
  "data": {
    "message": "Tasks created successfully",
    "taskIds": [
      "9c166d00-0921-406c-9b68-8409710223e2",
      "7a8f5b12-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
      "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e"
    ],
    "totalPosts": 3,
    "site": {
      "id": "site_123",
      "name": "Your Site Name"
    }
  }
}

GET/v1/posts/:id

Retrieve a post

This endpoint allows you to retrieve a single post by providing its ID. Refer to the list at the top of this page to see which properties are included with post objects.

Request

GET

/v1/posts/9c166d00-0921-406c-9b68-8409710223e2

curl https://api.waldium.com/api/v1/posts/9c166d00-0921-406c-9b68-8409710223e2 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "message": "Post retrieved successfully",
    "post": {
      "id": "9c166d00-0921-406c-9b68-8409710223e2",
      "slug": "getting-started-with-blogging",
      "title": "Getting Started with Blogging",
      "description": "A beginner's guide to blogging",
      "category": "Technology",
      "tags": ["blogging", "beginner", "guide"],
      "cta": null,
      "authorId": null,
      "isDraft": true,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    "site": {
      "id": "site_123",
      "name": "Your Site Name"
    }
  }
}

PUT/v1/posts/:id

Publish a post

This endpoint allows you to publish or unpublish a blog post by toggling its draft status. This endpoint automatically toggles the current draft status:

If post is a draft → Publishes it (sets isDraft to false)
If post is published → Makes it a draft (sets isDraft to true)

This endpoint does not require a request body.

Request

PUT

/v1/posts/9c166d00-0921-406c-9b68-8409710223e2

curl -X PUT https://api.waldium.com/api/v1/posts/9c166d00-0921-406c-9b68-8409710223e2 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "message": "Post published successfully",
    "post": {
      "id": "9c166d00-0921-406c-9b68-8409710223e2",
      "title": "Getting Started with Blogging",
      "isDraft": false,
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  }
}

DELETE/v1/posts/:id

Delete a post

This endpoint allows you to delete a blog post from your site. This action is permanent and cannot be undone. Note: This will also delete any associated data like analytics, comments, etc.

Request

DELETE

/v1/posts/9c166d00-0921-406c-9b68-8409710223e2

curl -X DELETE https://api.waldium.com/api/v1/posts/9c166d00-0921-406c-9b68-8409710223e2 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "message": "Post deleted successfully",
    "postId": "9c166d00-0921-406c-9b68-8409710223e2"
  }
}