REST API Integration

Connect BuzzRank to any CMS or platform via a generic REST API.

Overview

The REST API integration allows BuzzRank to publish articles directly to your platform by calling your REST API endpoints. Unlike webhooks (where your server receives requests), with REST API integration BuzzRank calls your API to create and manage content.

Use Case: Headless CMS (Strapi, Sanity, Contentful, Ghost), custom CMS with REST API, or any platform that exposes content management endpoints.

Configuration

Configure your REST API integration in BuzzRank Settings > Integrations > REST API.

API Base URL

The base URL of your API. BuzzRank will append endpoint paths to this URL.

https://your-cms.com/api

Authentication

Choose one of the following authentication methods:

Bearer Token

Sends Authorization: Bearer <token> header

API Key in Header

Sends custom header (default: X-API-Key: <key>)

No Authentication

No authentication headers sent (for internal/private networks)

Required Endpoints

Your API must implement the following endpoints. All requests include Content-Type: application/json.

POST/postsCreate new article

Called when publishing a new article. You must return the created post ID and optionally the URL.

Request Body:

{
  "title": "How to Optimize Your Website for SEO",
  "content": "<h2>Introduction</h2><p>SEO is important...</p>",
  "slug": "how-to-optimize-website-seo",
  "excerpt": "Learn the best practices for SEO optimization...",
  "featured_image_url": "https://images.buzzrank.io/abc123.jpg",
  "meta_title": "SEO Optimization Guide | Your Site",
  "meta_description": "Complete guide to optimizing your website...",
  "status": "draft" | "publish" | "scheduled",
  "scheduled_at": "2026-01-15T09:00:00.000Z",
  "structured_data": "{...JSON-LD...}",
  "author_id": 123
}

Response (required):

{
  "id": "post-123",
  "url": "https://yoursite.com/blog/how-to-optimize-website-seo"
}
PUT/posts/:idUpdate existing article

Called when updating an already published article. Only modified fields are included.

Request Body:

{
  "title": "Updated Title",
  "content": "<p>Updated content...</p>",
  "slug": "updated-slug",
  "meta_title": "Updated Meta Title",
  "meta_description": "Updated meta description",
  "status": "publish"
}

Response:

HTTP 200 OK
PATCH/posts/:idSchedule article

Called to schedule an article for future publishing.

Request Body:

{
  "status": "scheduled",
  "scheduled_at": "2026-01-15T09:00:00.000Z"
}

Response:

HTTP 200 OK
GET/posts/:idGet article details

Called to check the status of a published article.

Response:

{
  "id": "post-123",
  "url": "https://yoursite.com/blog/how-to-optimize-website-seo",
  "title": "How to Optimize Your Website for SEO",
  "content": "<h2>Introduction</h2><p>...</p>",
  "status": "publish",
  "publishedAt": "2026-01-11T12:00:00.000Z"
}
POST/mediaUpload image

Called to upload a featured image. Download the image from the provided URL and store it in your media library.

Request Body:

{
  "image_url": "https://images.buzzrank.io/generated-image-abc123.jpg"
}

Response (required):

{
  "id": "media-456",
  "url": "https://yoursite.com/uploads/image-abc123.jpg"
}

Error Handling

Return appropriate HTTP status codes for errors:

StatusMeaning
200Success
201Created (for POST /posts)
400Bad request (invalid data)
401Unauthorized (invalid token/key)
404Post not found
500Server error

Example Implementation (Express.js)

const express = require('express');
const app = express();
app.use(express.json());

// Middleware to verify Bearer token
function authenticate(req, res, next) {
  const auth = req.headers.authorization;
  if (!auth || !auth.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  const token = auth.slice(7);
  if (token !== process.env.API_TOKEN) {
    return res.status(401).json({ error: 'Invalid token' });
  }
  next();
}

// Create post
app.post('/api/posts', authenticate, async (req, res) => {
  try {
    const post = await createPostInYourCMS(req.body);
    res.status(201).json({ id: post.id, url: post.url });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Update post
app.put('/api/posts/:id', authenticate, async (req, res) => {
  try {
    await updatePostInYourCMS(req.params.id, req.body);
    res.status(200).json({ success: true });
  } catch (error) {
    if (error.code === 'NOT_FOUND') {
      return res.status(404).json({ error: 'Post not found' });
    }
    res.status(500).json({ error: error.message });
  }
});

// Schedule post
app.patch('/api/posts/:id', authenticate, async (req, res) => {
  try {
    await schedulePostInYourCMS(req.params.id, req.body.scheduled_at);
    res.status(200).json({ success: true });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Get post
app.get('/api/posts/:id', authenticate, async (req, res) => {
  try {
    const post = await getPostFromYourCMS(req.params.id);
    if (!post) {
      return res.status(404).json({ error: 'Post not found' });
    }
    res.json(post);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Upload media
app.post('/api/media', authenticate, async (req, res) => {
  try {
    const media = await uploadMediaToYourCMS(req.body.image_url);
    res.status(201).json({ id: media.id, url: media.url });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000);

Testing Your API

Test your API endpoints using curl:

# Test creating a post with Bearer token
curl -X POST https://your-api.com/api/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "title": "Test Article",
    "content": "<p>Test content</p>",
    "slug": "test-article",
    "status": "draft"
  }'

# Test with API Key header
curl -X POST https://your-api.com/api/posts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"title": "Test", "content": "<p>Test</p>", "slug": "test", "status": "draft"}'

# Test getting a post
curl -X GET https://your-api.com/api/posts/post-123 \
  -H "Authorization: Bearer YOUR_TOKEN"

REST API vs Webhook

REST APIWebhook
DirectionBuzzRank calls your APIYour server receives from BuzzRank
Your serverMust expose REST endpointsMust handle POST requests
AuthenticationBearer Token or API KeyHMAC signature verification
Best forStandard REST APIs, headless CMSCustom integrations, serverless

Need Help?

If you need assistance implementing your REST API integration, contact us at support@buzzrank.io