API overview

Base URL: https://comments.bootstrapware.co. Success responses are { "data": ... }. Errors are { "error": { "code", "message", "details?" } }. Health is GET /api/health.

Publishable content

Authorization: Bearer with bsw_test_pub_… or bsw_live_pub_…, plus the author-token rules in identity.

  • GET /api/v1/config/:appId
  • GET /api/v1/threads — query appId, tenantKey, resourceType, resourceId, filter, cursor, limit, viewerId, viewerToken
  • POST /api/v1/threads — createThread
  • GET /api/v1/threads/:id/comments
  • POST /api/v1/threads/:id/comments — reply
  • PATCH /api/v1/comments/:id — edit
  • POST /api/v1/comments/:id — { "action": "delete" }
  • POST /api/v1/threads/:id/resolve and /reopen
  • GET and POST /api/v1/threads/:id/read
  • GET /api/v1/stream — query scope, viewerId, viewerToken, key

Secret management

  • GET and POST /api/v1/apps
  • GET and PATCH /api/v1/apps/:id
  • POST /api/v1/apps/:id — { "action": "publish" }
  • GET /api/v1/usage
  • POST /api/v1/author-tokens
  • POST /api/v1/resources/purge
  • GET /api/v1/export
curl -s -X POST https://comments.bootstrapware.co/api/v1/author-tokens \
  -H "Authorization: Bearer $BSW_COMMENTS_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "authorId": "user_ada",
    "appId": "cma_demo",
    "tenantKey": "acme",
    "resourceType": "task",
    "resourceId": "task_1842",
    "permissions": ["read","create","reply","edit_own","delete_own"],
    "mentions": ["user_kai"],
    "expiresInSec": 300
  }'

$BSW_COMMENTS_SECRET is a placeholder for the dashboard secret (bsw_test_sec_… or bsw_live_sec_…). Do not commit the value. authorId in this server call is the session user your server already loaded, not a field copied from the browser.

Errors

  • invalid_key 401, forbidden 403, not_found 404, conflict 409, validation_error 422, rate_limited 429, quota_exceeded 403, db_unavailable 503.
  • Conflict reasons: stale_version, thread_resolved, idempotency_payload_mismatch, resource_frozen.

MCP

HTTP MCP is https://comments.bootstrapware.co/mcp. OAuth scope comments:mcp. Server id bootstrapware-comments. Tools: list_comment_apps, get_comment_app, create_comment_app, update_comment_draft, publish_comment_app, get_comment_published_config, get_comment_install_snippet, ensure_comment_test_publishable, list_comment_capabilities. Dashboard-only: live and secret key mint, webhooks, app delete, branding, billing, the Hosted discussion browser, export, and purge.

Related: Adapter · AGENTS.md · Webhooks