API Documentation

Integrate with Bublr programmatically

Getting Started

The Bublr API allows you to manage your posts and profile programmatically. You can list posts, read content, update your profile, and publish new articles via the API.

Base URL

https://bublr.life/api/v1

Authentication

All API requests require authentication using an API key. You can create API keys from your Profile Settings → Advanced.

Include your API key in the Authorization header:

Authorization: Bearer bublr_sk_your_api_key_here

Important: Keep your API keys secure. Never expose them in client-side code or public repositories. You can create up to 5 API keys and revoke them at any time.

Rate Limits

The API has the following rate limits to ensure fair usage:

• 100 requests per minute for read operations (GET)
• 30 requests per minute for write operations (POST, PUT, DELETE)

If you exceed these limits, you'll receive a 429 Too Many Requests response.

Endpoints

Profile

Response:

{
  "profile": {
    "name": "johndoe",
    "displayName": "John Doe",
    "about": "Writer and developer",
    "photo": "https://...",
    "link": "https://johndoe.com",
    "socialLinks": {
      "twitter": "johndoe",
      "github": "johndoe"
    },
    "skills": ["javascript", "react", "writing"],
    "postsCount": 12,
    "subscribersCount": 45
  }
}

Posts

Query Parameters:

• published — Filter by publish status (true or false)
• limit — Number of posts to return (default: 50, max: 100)
• offset — Number of posts to skip for pagination

Response:

{
  "posts": [
    {
      "id": "abc123",
      "slug": "my-first-post",
      "title": "My First Post",
      "excerpt": "A brief summary...",
      "published": true,
      "lastEdited": "2024-01-15T10:30:00.000Z",
      "createdAt": 1705312200000,
      "dotColor": "#4D96FF"
    }
  ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

Response:

{
  "post": {
    "id": "abc123",
    "slug": "my-first-post",
    "title": "My First Post",
    "excerpt": "A brief summary...",
    "content": "<p>Full HTML content...</p>",
    "published": true,
    "lastEdited": "2024-01-15T10:30:00.000Z",
    "createdAt": 1705312200000,
    "dotColor": "#4D96FF"
  }
}

Request Body:

{
  "title": "My New Post",        // Required, max 200 chars
  "excerpt": "A brief summary",  // Optional, max 500 chars
  "content": "<p>HTML content</p>", // Optional, max 500KB
  "slug": "my-new-post",         // Optional, auto-generated if not provided
  "published": false,            // Optional, default: false
  "dotColor": "#4D96FF"          // Optional, hex color
}

Response:

{
  "success": true,
  "post": {
    "id": "xyz789",
    "slug": "my-new-post",
    "title": "My New Post",
    "excerpt": "A brief summary",
    "published": false,
    "createdAt": 1705312200000
  },
  "message": "Post created as draft"
}

Request Body: (all fields optional)

{
  "title": "Updated Title",
  "excerpt": "Updated summary",
  "content": "<p>Updated content</p>",
  "published": true,
  "newSlug": "new-url-slug",
  "dotColor": "#FF6B6B"
}

Error Handling

The API returns consistent error responses with an error message and code:

{
  "error": "Invalid API key format. Keys should start with bublr_sk_",
  "code": "INVALID_KEY_FORMAT"
}

Common Error Codes:

• MISSING_AUTH — Authorization header not provided
• INVALID_KEY_FORMAT — API key format is invalid
• INVALID_KEY — API key not found or invalid
• KEY_REVOKED — API key has been revoked
• INVALID_INPUT — Request validation failed
• RATE_LIMITED — Too many requests

Example: Publishing a Post with cURL

curl -X POST https://bublr.life/api/v1/posts \
  -H "Authorization: Bearer bublr_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Hello from the API",
    "excerpt": "My first API-published post",
    "content": "<p>This post was created via the Bublr API!</p>",
    "published": true
  }'

JavaScript Example

const BUBLR_API_KEY = 'bublr_sk_your_api_key';
const BASE_URL = 'https://bublr.life/api/v1';

// Fetch all published posts
async function getPosts() {
  const response = await fetch(`${BASE_URL}/posts?published=true`, {
    headers: {
      'Authorization': `Bearer ${BUBLR_API_KEY}`
    }
  });
  return response.json();
}

// Create a new post
async function createPost(title, content) {
  const response = await fetch(`${BASE_URL}/posts`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${BUBLR_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ title, content, published: true })
  });
  return response.json();
}

Content Moderation

When publishing posts via the API, content is automatically moderated for spam, inappropriate content, and policy violations. If content is flagged, the post will be created but not published, and the response will include moderation details:

{
  "success": true,
  "post": {
    "id": "xyz789",
    "slug": "my-post",
    "published": false
  },
  "moderated": true,
  "moderationReason": "Content flagged as promotional spam",
  "message": "Post created but not published due to content moderation"
}

Other Documentation

• Newsletter Email Templates — Customize the emails sent to your subscribers