Automating Your Blog with the Waldium API

The Waldium API lets you programmatically manage your blog—create posts, generate content, upload documents, and more—all without touching the dashboard. This opens up powerful automation possibilities for developers and power users.

Why Use the API?

Automation: Create workflows that publish content automatically

Integration: Connect Waldium to your existing tools and systems

Scalability: Manage multiple posts or blogs efficiently

Custom Workflows: Build exactly the process you need

Bulk Operations: Perform actions on many posts at once

CI/CD Integration: Publish content as part of your deployment pipeline

API Access

The Waldium API is available on Pro and Custom plans.

Getting Your API Key

1. Navigate to Settings → API Keys in your dashboard
2. Click "Create API Key"
3. Give it a descriptive name (e.g., "Production Server")
4. Copy the key immediately (you won't see it again)
5. Store it securely (treat it like a password)

Security Note: Never commit API keys to version control or share them publicly.

API Basics

Base URL: https://api.waldium.com/api/v1

Authentication: Bearer token in the Authorization header

Format: JSON for requests and responses

Rate Limits: 100 requests per minute (Pro plan), custom for enterprise

Making Your First API Call

Here's a simple example to list your posts:

curl -X GET https://api.waldium.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.waldium.com/api/v1/posts', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const posts = await response.json();
console.log(posts);

import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
response = requests.get('https://api.waldium.com/api/v1/posts', headers=headers)
posts = response.json()
print(posts)

Key API Endpoints

Let's explore the most useful endpoints for automation.

Posts

List all posts

GET /api/v1/posts

Returns all your posts with metadata

Get a specific post

GET /api/v1/posts/:id

Retrieve full details of one post

Create a post

POST /api/v1/posts

Create a new blog post with content

Generate a post with AI

POST /api/v1/posts/generate

Let AI create content for you

Update a post

PUT /api/v1/posts/:id

Modify an existing post

Delete a post

DELETE /api/v1/posts/:id

Remove a post permanently

Publish a post

POST /api/v1/posts/:id/publish

Change a draft to published status

Knowledge Base

Upload a document

POST /api/v1/knowledge

Add files to your knowledge base (multipart/form-data)

List knowledge items

GET /api/v1/knowledge

See all uploaded documents

Delete a knowledge item

DELETE /api/v1/knowledge/:id

Remove a document from your knowledge base

Common Use Cases

Let's look at practical automation scenarios.

Auto-Publish from GitHub

Automatically create blog posts when you push markdown files to GitHub.

Workflow:

1. Write post in markdown in your repo
2. Push to GitHub
3. GitHub Action triggers
4. Action calls Waldium API to create post
5. Post appears on your blog

GitHub Action Example:

name: Publish to Waldium

on:
  push:
    paths:
      - 'posts/**'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Publish to Waldium
        run: |
          curl -X POST https://api.waldium.com/api/v1/posts \
            -H "Authorization: Bearer ${{ secrets.WALDIUM_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d @posts/latest.json

Content Calendar Automation

Schedule posts to publish automatically at specific times.

Approach:

1. Create posts as drafts via API
2. Set up a cron job or scheduled task
3. At publish time, call the publish endpoint
4. Post goes live automatically

Example with Node.js:

const cron = require('node-cron');

// Schedule for every day at 9 AM
cron.schedule('0 9 * * *', async () => {
  const drafts = await fetch('https://api.waldium.com/api/v1/posts?status=draft', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }).then(r => r.json());
  
  // Publish posts scheduled for today
  for (const post of drafts) {
    if (shouldPublishToday(post.scheduledDate)) {
      await fetch(`https://api.waldium.com/api/v1/posts/${post.id}/publish`, {
        method: 'POST',
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      });
    }
  }
});

Bulk Content Generation

Generate multiple posts at once based on a list of topics.

import requests
import time

topics = [
    "Getting Started with React Hooks",
    "Understanding TypeScript Generics",
    "Building REST APIs with Express",
    "Docker Best Practices for Node.js"
]

headers = {'Authorization': 'Bearer YOUR_API_KEY'}

for topic in topics:
    response = requests.post(
        'https://api.waldium.com/api/v1/posts/generate',
        headers=headers,
        json={
            'topic': topic,
            'style': 'technical',
            'length': 'medium',
            'tone': 'informative',
            'useKnowledge': True
        }
    )
    
    if response.status_code == 200:
        print(f"✓ Generated: {topic}")
    else:
        print(f"✗ Failed: {topic}")
    
    # Rate limiting: wait between requests
    time.sleep(2)

Integration with CMS

Sync content from your existing CMS to Waldium.

Workflow:

1. Export content from your CMS (WordPress, Contentful, etc.)
2. Transform to Waldium format
3. Use API to import posts
4. Your blog now has all your content

Example:

async function syncFromCMS() {
  // Fetch from your CMS
  const cmsContent = await fetchFromWordPress();
  
  // Transform and import
  for (const article of cmsContent) {
    const waldiumPost = {
      title: article.title,
      content: article.content,
      description: article.excerpt,
      category: article.category,
      tags: article.tags,
      isDraft: false
    };
    
    await fetch('https://api.waldium.com/api/v1/posts', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(waldiumPost)
    });
  }
}

Automated Knowledge Base Updates

Keep your knowledge base current by automatically uploading documentation.

const fs = require('fs');
const FormData = require('form-data');

async function uploadDocs() {
  const files = fs.readdirSync('./docs');
  
  for (const file of files) {
    const form = new FormData();
    form.append('file', fs.createReadStream(`./docs/${file}`));
    
    await fetch('https://api.waldium.com/api/v1/knowledge', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        ...form.getHeaders()
      },
      body: form
    });
    
    console.log(`Uploaded: ${file}`);
  }
}

// Run daily to sync docs
uploadDocs();

Webhooks

Get notified when events happen on your blog (Pro plan feature).

Available Events

• post.published - A post went live
• post.updated - Post content was changed
• post.deleted - A post was removed
• knowledge.uploaded - Document added to knowledge base

Setting Up Webhooks

1. Go to Settings → Webhooks
2. Click "Create Webhook"
3. Enter your endpoint URL
4. Select events to listen for
5. Save and test

Webhook Payload Example

When a post is published:

{
  "event": "post.published",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "postId": "clx123abc",
    "title": "Getting Started with Waldium",
    "slug": "getting-started-with-waldium",
    "url": "https://yourblog.com/getting-started-with-waldium",
    "publishedAt": "2024-01-15T10:30:00Z"
  }
}

Webhook Use Cases

Social Media Auto-Posting: Post to Twitter/LinkedIn when content publishes

Slack Notifications: Alert your team when posts go live

Analytics Tracking: Log publishing events to your analytics system

Email Campaigns: Trigger email sends for new content

Content Distribution: Automatically syndicate to Medium, Dev.to, etc.

Error Handling

Always handle errors gracefully in your API integrations.

HTTP Status Codes

• 200 OK - Request succeeded
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request format
• 401 Unauthorized - Invalid or missing API key
• 404 Not Found - Resource doesn't exist
• 429 Too Many Requests - Rate limit exceeded
• 500 Server Error - Something went wrong on our end

Example Error Handling

async function createPost(postData) {
  try {
    const response = await fetch('https://api.waldium.com/api/v1/posts', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(postData)
    });
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.message}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('Failed to create post:', error);
    // Handle retry logic, logging, etc.
  }
}

Rate Limiting

Respect rate limits to avoid throttling:

Pro Plan: 100 requests per minute Custom Plan: Negotiated limits

Best Practices

Batch Operations: Group related API calls

Use Webhooks: Instead of polling for changes

Cache Responses: Don't refetch unchanged data

Exponential Backoff: If rate limited, wait before retrying

Monitor Usage: Track your API calls to stay within limits

Security Best Practices

Keep your API integration secure:

Store Keys Securely: Use environment variables or secrets management

Rotate Keys Regularly: Generate new keys periodically

Use HTTPS: Always use encrypted connections

Validate Webhooks: Verify webhook signatures (provided in headers)

Principle of Least Privilege: Only give API keys necessary permissions

Monitor Usage: Watch for unusual API activity

Testing and Development

Use Drafts: Test API calls with draft posts before going live

Test Environment: Consider using a separate Waldium site for testing

Logging: Log API requests and responses for debugging

Version Control: Track your API integration code in git

Documentation: Document your custom integrations for your team

API Documentation

For complete API reference with all endpoints, parameters, and examples:

Visit: docs.waldium.com/api

The documentation includes:

• Full endpoint reference
• Request/response examples
• Authentication details
• Error codes and handling
• SDKs and client libraries (coming soon)

What's Next?

Now that you understand the API, explore these advanced topics:

• Webhooks: Set up real-time notifications
• Batch Operations: Manage multiple posts efficiently
• Custom Integrations: Build tools specific to your workflow
• CI/CD Integration: Publish as part of your deployment

The API unlocks endless possibilities for automation. What will you build?

Ready to start coding? Grab your API key from Settings → API Keys and start experimenting! 🚀

Need help with API integration? Check out our documentation or email support@waldium.com.