SimplyStack Documentation

Overview

The Blog Posts API allows you to create, read, update, and delete blog posts with rich content support, SEO optimization, and categorization. Each blog post supports HTML content, metadata, tags, and publishing status.

✨ Key Features

• Rich HTML content support
• SEO metadata (title, description, keywords)
• Tags and categorization
• Draft and published states
• Excerpt generation
• Canonical URL support

Authentication

All blog post endpoints require authentication via the x-api-key header. Blog posts are automatically scoped to your project.

curl -H "x-api-key: your_api_key_here" \
     -H "Content-Type: application/json" \
     https://simplystack.dev/api/v1/blog

Endpoints

List Blog Posts

GET/api/v1/blog

Retrieve a list of blog posts with optional filtering.

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: `draft` or `published`
`category`	string	Filter by category
`limit`	number	Number of posts to return (default: 10, max: 100)
`offset`	number	Number of posts to skip (default: 0)

Example Request

curl -H "x-api-key: your_api_key_here" \
     "https://simplystack.dev/api/v1/blog?status=published&limit=5"

Example Response

{
  "data": [
    {
      "id": "post_123",
      "title": "Getting Started with SimplyStack",
      "content": "<h1>Welcome!</h1><p>This is a blog post...</p>",
      "excerpt": "Learn how to get started with SimplyStack",
      "status": "published",
      "category": "tutorials",
      "tags": ["getting-started", "tutorial"],
      "meta_title": "Getting Started Guide - SimplyStack",
      "meta_description": "Complete guide to getting started",
      "meta_keywords": ["tutorial", "guide"],
      "canonical_url": "https://example.com/getting-started",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ],
  "total": 1,
  "limit": 5,
  "offset": 0
}

Get Blog Post

GET/api/v1/blog/{id}

Retrieve a specific blog post by ID.

Example Request

curl -H "x-api-key: your_api_key_here" \
     "https://simplystack.dev/api/v1/blog/post_123"

Create Blog Post

POST/api/v1/blog

Create a new blog post.

Request Body

{
  "title": "My Blog Post",
  "content": "<h1>Welcome!</h1><p>This is the content...</p>",
  "excerpt": "Brief description of the post",
  "status": "draft", // or "published"
  "category": "tutorials",
  "tags": ["javascript", "tutorial"],
  "meta_title": "My Blog Post - SEO Title",
  "meta_description": "SEO description for search engines",
  "meta_keywords": ["blog", "tutorial"],
  "canonical_url": "https://example.com/my-blog-post"
}

Example Request

curl -X POST \
     -H "x-api-key: your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "Getting Started with SimplyStack",
       "content": "<h1>Welcome!</h1><p>Learn how to use SimplyStack...</p>",
       "status": "published",
       "category": "tutorials",
       "tags": ["getting-started"]
     }' \
     "https://simplystack.dev/api/v1/blog"

Update Blog Post

PUT/api/v1/blog/{id}

Update an existing blog post. Only provided fields will be updated.

Example Request

curl -X PUT \
     -H "x-api-key: your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "status": "published",
       "meta_description": "Updated SEO description"
     }' \
     "https://simplystack.dev/api/v1/blog/post_123"

Delete Blog Post

DELETE/api/v1/blog/{id}

Permanently delete a blog post. This action cannot be undone.

Example Request

curl -X DELETE \
     -H "x-api-key: your_api_key_here" \
     "https://simplystack.dev/api/v1/blog/post_123"

Blog Post Structure

Here's the complete structure of a blog post object:

interface BlogPost {
  id: string;                    // Unique identifier
  title: string;                 // Post title
  content: string;               // HTML content
  excerpt?: string;              // Brief description
  status: "draft" | "published"; // Publication status
  category?: string;             // Post category
  tags?: string[];              // Array of tags
  meta_title?: string;          // SEO title
  meta_description?: string;    // SEO description
  meta_keywords?: string[];     // SEO keywords
  canonical_url?: string;       // Canonical URL for SEO
  created_at: string;           // ISO timestamp
  updated_at: string;           // ISO timestamp
}

Error Handling

The Blog API returns standard HTTP status codes and detailed error messages:

400 Bad Request

Invalid request data or missing required fields.

401 Unauthorized

Missing or invalid API key.

404 Not Found

Blog post not found or doesn't belong to your project.

429 Too Many Requests

Rate limit exceeded. Please wait before making more requests.

SDK Usage

For easier integration, use the SimplyStack TypeScript SDK:

import { SimplyStackSDK } from "@simplystack-org/sdk";

const sdk = new SimplyStackSDK("your-api-key");

// Create a blog post
const { data: post, error } = await sdk.createBlogPost({
  title: "My First Post",
  content: "<h1>Hello World!</h1>",
  status: "published",
  tags: ["getting-started"]
});

// Get all published posts
const { data: posts } = await sdk.getBlogPosts({
  status: "published"
});

// Update a post
const { data: updatedPost } = await sdk.updateBlogPost("post_123", {
  status: "published"
});