API Reference

Sites API

The Sites API lets you manage your connected websites programmatically — add sites, retrieve credentials, test delivery, and rotate keys.

Site Object

{
  "id": "site_abc123",
  "name": "My Tech Blog",
  "url": "https://mytechblog.com",
  "webhook_url": "https://mytechblog.com/api/blogree",
  "api_key": "bk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "webhook_secret": "whs_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "niche": "Technology & Software",
  "platform": "nextjs",  // detected platform: nextjs, wordpress, gatsby, custom
  "status": "active",    // active, inactive, error
  "delivery_stats": {
    "total": 412,
    "success_rate": 99.3,
    "last_delivery": "2026-04-02T09:01:14Z"
  },
  "created_at": "2026-01-15T10:00:00Z"
}

List Sites

GET/api/sites

GET /api/sites
Authorization: Bearer <token>

// Response
{
  "sites": [
    { ...Site object },
    { ...Site object }
  ],
  "total": 3
}

Get Site

GET/api/sites/:id

GET /api/sites/site_abc123
Authorization: Bearer <token>

// Returns full Site object including api_key and webhook_secret

Create Site

POST/api/sites

POST /api/sites
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "My Tech Blog",
  "url": "https://mytechblog.com",
  "webhook_url": "https://mytechblog.com/api/blogree",
  "platform": "nextjs"  // optional: nextjs, wordpress, gatsby, sveltekit, custom
}

// Response: full Site object with generated api_key and webhook_secret

Update Site

PATCH/api/sites/:id

PATCH /api/sites/site_abc123
Authorization: Bearer <token>

{
  "name": "Updated Blog Name",
  "webhook_url": "https://mytechblog.com/api/new-endpoint"
}

// Returns updated Site object

Rotate Credentials

POST/api/sites/:id/rotate-keys

Generates new API Key and Webhook Secret. Old credentials stop working immediately.

POST /api/sites/site_abc123/rotate-keys
Authorization: Bearer <token>

// Response
{
  "site_id": "site_abc123",
  "new_api_key": "bk_live_newkeyxxxxxxxxxxxxxxxxxxx",
  "new_webhook_secret": "whs_newSecretxxxxxxxxxxxxxxxx",
  "rotated_at": "2026-04-02T14:30:00Z",
  "warning": "Update your environment variables immediately — old credentials are now invalid"
}

Test Delivery

POST/api/sites/:id/test-delivery

Sends a sample test webhook payload to your site's endpoint. Use this to verify your webhook handler is correctly configured before publishing real posts.

POST /api/sites/site_abc123/test-delivery
Authorization: Bearer <token>

// Response
{
  "success": true,
  "response_code": 200,
  "response_time_ms": 834,
  "payload_sent": { ...sample Post object },
  "message": "Test delivery successful — your endpoint is correctly configured"
}

// Or on failure:
{
  "success": false,
  "response_code": 404,
  "response_time_ms": 1200,
  "error": "Webhook URL returned 404 Not Found",
  "troubleshooting": "Verify the webhook URL matches your route handler exactly"
}

Delete Site

DELETE/api/sites/:id

Permanently removes the site from your account. All associated delivery history is retained in analytics for 90 days.

DELETE /api/sites/site_abc123
Authorization: Bearer <token>

// Response: 204 No Content