API Overview

Complete reference for the Boring API endpoints, authentication, and general usage.

Base URL

https://boring.aiagent-me.com

All API requests should be made to this base URL.

Authentication

API Key Authentication

All API requests (except OAuth callbacks) require an API key in the request header:

boring-api-key: boring_xxxxxxxxxxxxx

How to get an API key:

  1. Sign in to the Boring Dashboard
  2. Navigate to the Settings page
  3. Click "Generate New API Key"
  4. Copy and store the key securely

See the API Keys guide for more details.

Request Format

Content Type

All requests must include:

Content-Type: application/json

Request Body

The request body should be valid JSON:

{
  "post": {
    "accountId": "uuid-string",
    "content": {
      "text": "Post content",
      "mediaUrls": ["https://example.com/image.jpg"],
      "platform": "facebook|instagram|threads"
    },
    "target": {
      "targetType": "facebook|instagram|threads"
    }
  }
}

Response Format

Success Response

All successful responses return JSON with success: true:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // Response-specific data
  }
}

Error Response

All error responses return JSON with success: false:

{
  "success": false,
  "error": "Error type",
  "message": "Detailed error message"
}

Common HTTP status codes:

See Errors for complete error reference.

Endpoints

Publishing API

Method Endpoint Description Auth Required
POST /v2/posts Publish content to social platforms API Key

See Publishing for detailed documentation.

Account Management

Method Endpoint Description Auth Required
GET /api/accounts List connected accounts Session
DELETE /api/accounts/{id} Disconnect account Session
POST /api/token/info Validate token Session

Note: Account management endpoints require dashboard authentication (session cookie), not an API key.

Publishing History

Method Endpoint Description Auth Required
GET /api/published-posts Get publish history Session

Query parameters:

Note: Requires dashboard authentication.

API Key Management

Method Endpoint Description Auth Required
GET /api/keys List API keys Session
POST /api/keys Generate new API key Session
DELETE /api/keys/{id} Delete API key Session

Note: Requires dashboard authentication.

Rate Limits

Rate limits vary by platform:

Platform Limit Window
Facebook 200 calls Per hour per page
Instagram 200 calls Per hour per user
Threads 250 calls Per hour per user

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 150
X-RateLimit-Reset: 1642780800

Handling Rate Limits

If you exceed rate limits, you'll receive:

{
  "success": false,
  "error": "RateLimitExceeded",
  "message": "Rate limit exceeded. Try again in 3600 seconds.",
  "retry_after": 3600
}

Best practices:

Subscription Plans & Usage Limits

Boring API offers two subscription plans with different usage limits:

Free Plan

Pro Plan

Checking Your Usage

To check your current API usage and subscription status:

Endpoint: GET /api/subscription/status

Authentication: Requires session authentication (dashboard login)

Request Example:

curl -X GET https://boring.aiagent-me.com/api/subscription/status \
  -H "Cookie: boring_token=YOUR_JWT_TOKEN"

Response for Free Plan:

{
  "success": true,
  "subscription": {
    "status": "free",
    "plan": "free"
  },
  "api_usage": {
    "current_usage": 5,
    "limit": 10,
    "remaining": 5,
    "current_month": "2025-12"
  }
}

Response for Pro Plan:

{
  "success": true,
  "subscription": {
    "status": "active",
    "plan": "pro",
    "plan_type": "annual",
    "current_period_end": "2026-12-05T00:00:00Z"
  },
  "api_usage": {
    "current_usage": 150,
    "limit": -1,
    "remaining": -1,
    "current_month": "2025-12"
  }
}

Response Fields:

Usage Limit Exceeded

When Free plan users exceed 10 API calls per month, the API returns:

HTTP Status: 429 Too Many Requests

Response:

{
  "error": "本月使用次數已滿，請升級到 Pro 方案或等待下個月",
  "error_en": "Monthly usage limit reached. Please upgrade to Pro plan or wait for next month.",
  "current_usage": 10,
  "limit": 10,
  "plan": "free"
}

Upgrading to Pro

To upgrade from Free to Pro plan:

  1. Visit the Boring Dashboard
  2. Click the "Upgrade to Pro" button
  3. Choose annual (save 33%) or monthly billing
  4. Complete payment via Stripe
  5. Start using unlimited API calls immediately

Idempotency

The Boring API does not currently support idempotency keys. Duplicate requests will create duplicate posts.

Recommendation: Implement your own deduplication logic using the post_submission_id from responses.

Pagination

Currently, only the publishing history endpoint supports pagination:

GET /api/published-posts?limit=20&offset=0

Parameters:

Response:

{
  "posts": [...],
  "total": 150,
  "limit": 20,
  "offset": 0
}

Timeouts

If a request times out:

Webhooks

Webhooks are not currently supported. To monitor publishing status:

API Versioning

Current API version: v2

Version is included in the endpoint path:

POST /v2/posts

Deprecation policy:

SDK Support

Official SDKs:

Currently, use standard HTTP libraries:

See Examples for code samples.

Testing

Test Accounts

Use your own test accounts:

Sandbox Mode

There is no sandbox mode. All API calls publish to live accounts.

Recommendation:

Best Practices

1. Error Handling

Always handle errors gracefully:

try:
    response = requests.post(API_URL, headers=headers, json=data)
    result = response.json()

    if not result.get("success"):
        log_error(result["message"])
        notify_admin(result)
        return None

    return result["data"]

except requests.exceptions.Timeout:
    log_error("Request timed out")
    # Retry logic here

except requests.exceptions.RequestException as e:
    log_error(f"Request failed: {e}")
    # Handle network errors

2. Retry Logic

Implement exponential backoff:

import time

def publish_with_retry(data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(API_URL, headers=headers, json=data)
            result = response.json()

            if result.get("success"):
                return result

            if result.get("error") == "RateLimitExceeded":
                wait_time = result.get("retry_after", 60)
                time.sleep(wait_time)
                continue

        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff

    return None

3. Logging

Log all API interactions:

import logging

logger = logging.getLogger(__name__)

logger.info(f"Publishing to {platform}: {account_id}")
response = requests.post(API_URL, headers=headers, json=data)
logger.info(f"Response: {response.status_code} - {response.text}")

4. Security

5. Performance

Support

Need help?

Next Steps