API Reference

Base URL: https://app.ollabear.com. The external/integration surface is documented here; dashboard-only endpoints are out of scope.

Authentication

Mint a PAT in Settings → API Tokens. The token value is shown once.

Scopes

write implies read. Out-of-scope use returns 403.

Integrations API (/v1/integrations)

# List open conversations
curl -H "Authorization: Bearer pat_live_…" \
  "https://app.ollabear.com/v1/integrations/conversations?status=open&limit=50"

# Post a message
curl -X POST -H "Authorization: Bearer pat_live_…" -H "Content-Type: application/json" \
  -d '{"content":"Your order ships today."}' \
  https://app.ollabear.com/v1/integrations/conversations/{id}/messages

# Update status / tags
curl -X PATCH -H "Authorization: Bearer pat_live_…" -H "Content-Type: application/json" \
  -d '{"status":"closed"}' \
  https://app.ollabear.com/v1/integrations/conversations/{id}/status

Webhooks (outbound)

Register a webhook to receive events. The signing secret is returned once.

curl -X POST -H "Authorization: Bearer pat_live_…" -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/ollabear","events":["message.created","conversation.closed"]}' \
  https://app.ollabear.com/v1/integrations/webhooks

Each delivery carries X-Webhook-Signature: <hex HMAC-SHA256(rawBody, secret)> and X-Webhook-Event. Delivery is synchronous, ≤ 60/min per webhook, SSRF-guarded. Verify the signature before trusting the payload:

import crypto from 'node:crypto';
const expected = crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-webhook-signature']));

Event payload (message.created):

{
  "event": "message.created",
  "project_id": "…",
  "conversation_id": "…",
  "message": { "id":"…","role":"visitor","content":"Where is my order?","created_at":"2026-06-18T10:00:00Z" }
}

Widget API (/v1/widget)

Called by the embedded widget with X-API-Key: qk_… and an allowed Origin (set at onboarding / Shopify install). POST /v1/widget/conversations starts a conversation; POST /v1/widget/conversations/{id}/messages sends a visitor message (the AI reply arrives over the websocket).

Shopify

GET /shopify/install?shop=acme.myshopify.com → OAuth. The four mandatory webhooks (app/uninstalled, customers/data_request, customers/redact, shop/redact) are verified via X-Shopify-Hmac-Sha256 = base64(HMAC-SHA256(rawBody, app secret)) and return 200 on a valid signature.

Shopify’s OAuth HMAC (hex, sorted query params) and webhook HMAC (base64, raw body) are different schemes — don’t reuse verification code across them.

Errors

Timestamps are RFC 3339 UTC; IDs are UUIDs; pagination is cursor-based (next_cursor → ?cursor=). The machine-readable OpenAPI 3.1 spec is the source of truth — generate clients from it.