Web Embed API

REST API for managing Canopi embed instances. Authenticated routes require a Bearer JWT from the Canopi sign-in flow.

Base URL: https://api.canopi.live/api/embeds

Authentication

Authorization: Bearer <jwt>

Obtain JWT by signing in through the extension or embed auth flow (POST /api/auth/web3auth).

Public endpoints

Get embed config

Used by the embed loader — no auth required.

GET /api/embeds/config/:canopiId

Response (200):

{
  "id": "abc123xyz",
  "communityId": "uuid",
  "domainWhitelist": ["example.com"],
  "pageRules": {
    "type": "patterns",
    "patterns": ["/help/*"]
  },
  "triggerConfig": {
    "type": "corner-tab",
    "position": "bottom-right",
    "message": "Need help?",
    "color": "#6366f1"
  },
  "status": "active"
}

Client config

Global client-side flags for embed runtime.

GET /api/embeds/client-config

Analytics event (public ingest)

POST /api/embeds/analytics/events
Content-Type: application/json

{
  "canopiId": "abc123",
  "event": "trigger_click",
  "pageUrl": "https://example.com/help/faq"
}

Authenticated endpoints

Create instance

POST /api/embeds/instances
Content-Type: application/json
Authorization: Bearer <jwt>

Body:

{
  "name": "Help Center Support",
  "description": "Sidebar for help pages",
  "communityId": "uuid-of-community",
  "domainWhitelist": ["example.com", "www.example.com"],
  "pageRules": {
    "type": "patterns",
    "patterns": ["/help/*", "/docs/*"]
  },
  "triggerConfig": {
    "type": "corner-tab",
    "position": "bottom-right",
    "message": "Need help? Chat with us!",
    "color": "#6366f1",
    "size": "medium"
  }
}

Response (201): instance object including generated embedCode.

List instances

GET /api/embeds/instances
Authorization: Bearer <jwt>

Get instance

GET /api/embeds/instances/:id
Authorization: Bearer <jwt>

Update instance

PUT /api/embeds/instances/:id
Authorization: Bearer <jwt>

Delete instance

DELETE /api/embeds/instances/:id
Authorization: Bearer <jwt>

Analytics summary

GET /api/embeds/analytics/:id
Authorization: Bearer <jwt>

Domain blacklist

GET /api/embeds/instances/:id/blacklist
PUT /api/embeds/instances/:id/blacklist
Authorization: Bearer <jwt>

Status codes

Code	Meaning
200	Success
201	Created
400	Invalid body
401	Missing or invalid token
403	Forbidden (wrong user / domain)
404	Instance not found

Embed code format

The dashboard generates:

<script
  src="https://app.canopi.live/embed/v1.js"
  data-canopi-id="abc123xyz"
  async
></script>

Related

• Quick start
• Domains & endpoints

Full internal spec: docs/WEB_EMBED_SDK_API_SPEC.md in the repo.