ASQ API Reference

Thread-native community Q&A — REST API with configurable role-based access control

Base URL for all API requests:

https://api.asq.ai/v1

Every request scopes to a community. Most endpoints follow the pattern:

/v1/communities/{communityId}/resource

Authentication

ASQ supports two auth modes. All requests require an Authorization header.

1. Firebase Auth Token (widget / client-side)

Authorization: Bearer {firebase_id_token}

Used by the embedded widget. The token carries the user's UID and custom claims (including role).

2. API Key + Secret (server-to-server)

Authorization: ApiKey {api_key}:{api_secret}
X-ASQ-As: {user_id}  

Used for backend integrations, pre-seeding sessions, bulk imports, and admin operations. API keys are created in the community dashboard and scoped to a role.

Permission Model

ASQ uses a capability-based RBAC system. Each community defines roles, and each role is a set of capability flags. This means permissions are fully configurable — you decide exactly what each role can and cannot do.

How it works

Each user has a role per community. A user can be admin in one community and viewer in another. Roles are stored in the user's community membership document.

{
  "userId": "usr_abc123",
  "communityId": "expo-2026",
  "role": "speaker",
  "customCapabilities": {           // optional overrides
    "session.create": true,
    "thread.create": true,
    "tag.manage": false
  },
  "joinedAt": "2026-03-28T10:00:00Z"
}

Roles & Capabilities

ASQ ships with 6 default roles. All are fully configurable — rename them, change their capabilities, or create entirely new roles.

Default Roles

✓ = always on   CFG = configurable (off by default)   — = always off unless custom override

Community Configuration

Each community stores its permission config, session defaults, and feature flags in a single config document.

{
  "communityId": "expo-2026",
  "name": "PM Career Expo 2026",
  "features": {
    "sessions": true,
    "rooms": true,
    "knowledge": true,
    "tags": true,
    "meetingLinks": true,
    "dm": false
  },
  "defaults": {
    "sessionModes": ["ask-session","private-room","public-convo","ama","workshop"],
    "sessionCategories": ["exhibitor","speaker","community","sponsor"],
    "maxParticipantsDefault": 25,
    "sessionDurationDefault": 45,
    "threadVisibility": "community",
    "autoSummarize": true
  },
  "roles": {
    "admin":     { "capabilities": { "session.create":true, "session.manage":true, "thread.create":true, "thread.reply":true, "thread.read":true, "room.create":true, "room.join":true, "room.message":true, "tag.create":true, "tag.manage":true, "tag.assign":true, "member.invite":true, "member.list":true, "member.manage":true, "knowledge.read":true, "knowledge.curate":true, "community.configure":true, "analytics.view":true }},
    "organizer": { "capabilities": { "session.create":true, "session.manage":true, "thread.create":true, "thread.reply":true, "thread.read":true, "room.create":true, "room.join":true, "room.message":true, "tag.create":true, "tag.manage":true, "tag.assign":true, "member.invite":true, "member.list":true, "member.manage":true, "knowledge.read":true, "knowledge.curate":true, "community.configure":false, "analytics.view":true }},
    "speaker":   { "capabilities": { "session.create":true, "thread.create":true, "thread.reply":true, "thread.read":true, "room.create":true, "room.join":true, "room.message":true, "tag.create":true, "tag.assign":true, "member.list":true, "knowledge.read":true, "knowledge.curate":true }},
    "exhibitor": { "capabilities": { "session.create":true, "thread.create":true, "thread.reply":true, "thread.read":true, "room.create":true, "room.join":true, "room.message":true, "tag.assign":true, "member.list":true, "knowledge.read":true }},
    "member":    { "capabilities": { "thread.reply":true, "thread.read":true, "room.join":true, "room.message":true, "member.list":true, "knowledge.read":true, "session.join":true }},
    "viewer":    { "capabilities": { "thread.read":true, "member.list":true, "knowledge.read":true }}
  },
  "registrationDefaults": {
    "defaultRole": "member",
    "approvalRequired": false,
    "allowSelfRegister": true
  }
}

Role Templates

Create custom roles for your community. Roles are just named capability bundles.

{
  "name": "panelist",
  "label": "Panel Speaker",
  "description": "Can create AMA sessions and threads, but not manage tags",
  "capabilities": {
    "session.create": true,
    "session.join": true,
    "thread.create": true,
    "thread.reply": true,
    "thread.read": true,
    "room.create": true,
    "room.join": true,
    "room.message": true,
    "tag.assign": true,
    "member.list": true,
    "knowledge.read": true,
    "knowledge.curate": true
  },
  "sessionModes": ["ama", "public-convo"],
  "maxSessions": 3
}

{
  "id": "role_panelist",
  "name": "panelist",
  "label": "Panel Speaker",
  "capabilities": { ... },
  "createdAt": "2026-03-28T10:00:00Z"
}

{
  "capabilities": {
    "tag.create": true,
    "member.invite": true
  }
}

Capability Flags Reference

Sessions

Sessions are scheduled or live rooms — AMAs, workshops, exhibitor booths, public conversations. They can be pre-created by the API for conferences or created on-the-fly by users with the right role.

{
  "title": "Building Products That Scale",
  "description": "Interactive AMA with product leaders",
  "mode": "ama",
  "category": "speaker",
  "status": "scheduled",
  "scheduledAt": "2026-04-15T14:00:00Z",
  "duration": 60,
  "maxParticipants": 50,
  "meetLink": "https://meet.google.com/abc-defg-hij",
  "visibility": "public",
  "tags": ["product","leadership","scaling"],
  "hosts": ["usr_sarah","usr_mike"],
  "preCreatedThreads": [
    {
      "title": "What's the biggest mistake PMs make at Series B?",
      "body": "Seed question for the AMA",
      "tags": ["series-b","mistakes"],
      "pinned": true
    },
    {
      "title": "How do you prioritize when everything is P0?",
      "body": "Common question — let's dig in",
      "tags": ["prioritization"]
    }
  ],
  "settings": {
    "allowAudienceThreads": true,
    "requireApproval": false,
    "autoRecord": true,
    "autoSummarize": true
  }
}

{
  "id": "ses_abc123",
  "title": "Building Products That Scale",
  "mode": "ama",
  "category": "speaker",
  "status": "live",
  "participantCount": 34,
  "threads": [ ... ],
  "userPermissions": {
    "canPost": true,
    "canReply": true,
    "canManage": false,
    "canJoinCall": true
  }
}

{ "status": "live", "meetLink": "https://zoom.us/j/123456" }

{
  "sessions": [
    { "title": "...", "mode": "ama", ... },
    { "title": "...", "mode": "workshop", ... }
  ],
  "defaults": {
    "category": "exhibitor",
    "visibility": "public",
    "maxParticipants": 30
  }
}

Threads

Threads are the core unit — a structured question that can attract answers, spawn rooms, and generate knowledge.

{
  "title": "How to handle stakeholder misalignment?",
  "body": "Our leadership team has conflicting priorities...",
  "askType": "ask-session",
  "sessionId": "ses_abc123",
  "tags": ["stakeholders","alignment"],
  "visibility": "community",
  "meetLink": "https://meet.google.com/xyz",
  "matchCriteria": {
    "expertise": ["product-strategy","leadership"],
    "minTrust": 70
  }
}

{ "body": "In my experience at Stripe, we solved this by...", "parentId": null }

{ "meetLink": "https://teams.microsoft.com/l/meetup/...", "maxParticipants": 8 }

Rooms

Live conversation spaces. Always linked to a thread or session.

{ "body": "Great point — I think the key insight is...", "type": "text" }

Members

Manage community members, their roles, and per-user capability overrides.

{
  "email": "[email protected]",
  "role": "speaker",
  "customCapabilities": {
    "tag.create": true
  },
  "sessionAccess": ["ses_abc123", "ses_def456"],
  "sendInvite": true
}

{
  "role": "exhibitor",
  "customCapabilities": {
    "session.create": true,
    "tag.create": true,
    "member.invite": true
  }
}

{
  "members": [
    { "email": "[email protected]", "role": "exhibitor", "name": "Acme Corp" },
    { "email": "[email protected]", "role": "speaker", "name": "Jane Doe" }
  ],
  "defaults": { "sendInvite": true }
}

Tags

Community taxonomy for organizing threads and sessions. Tags can be hierarchical.

{ "name": "product-strategy", "parentId": "tag_product", "color": "#6366f1" }

{ "mergeInto": "tag_product_strategy" }

Knowledge

Auto-generated summaries from resolved threads and completed rooms. The end product of ASQ's pipeline: Question → Room → Summary → Knowledge.

{ "status": "approved", "editedSummary": "Refined summary text..." }

Widget Embed

Drop the ASQ widget into any website with 3 lines of code. The widget inherits the community's permission model — users see only what their role allows.

Quick Start

<!-- 1. Load ASQ -->
<script src="https://cdn.asq.ai/v1/asq.js"></script>
<link rel="stylesheet" href="https://cdn.asq.ai/v1/asq.css">

<!-- 2. Initialize -->
<script>
  ASQ.init({
    communityId: 'expo-2026',
    firebaseConfig: { /* your config */ },
    theme: 'light',
    position: 'bottom-right',
    features: {
      sessions: true,
      people: true,
      knowledge: true
    }
  });
</script>

Configuration Options

SSO Integration

For platforms that have their own auth, pass a signed JWT to auto-login users:

ASQ.init({
  communityId: 'expo-2026',
  firebaseConfig: { ... },
  ssoToken: 'eyJhbG...',          // JWT signed with your ASQ API secret
  ssoProvider: 'custom',
  userMapping: {
    id: 'sub',                     // JWT claim → ASQ user ID
    name: 'name',
    email: 'email',
    role: 'asq_role'               // optional: auto-assign role from JWT
  }
});

JavaScript API

// Open/close widget programmatically
ASQ.open();
ASQ.close();
ASQ.toggle();

// Navigate to a specific session
ASQ.openSession('ses_abc123');

// Listen for events
ASQ.on('thread.created', (thread) => { ... });
ASQ.on('room.joined', (room) => { ... });
ASQ.on('session.started', (session) => { ... });

// Pre-fill a new thread
ASQ.createThread({
  title: 'Question from the audience',
  sessionId: 'ses_abc123',
  tags: ['live-qa']
});

Webhooks

Get notified when things happen in your community. Configure webhooks in the dashboard or via API.

{
  "url": "https://yoursite.com/asq-webhook",
  "secret": "whsec_...",
  "events": [
    "session.created",
    "session.started",
    "session.ended",
    "thread.created",
    "thread.solved",
    "room.started",
    "room.ended",
    "member.joined",
    "knowledge.generated"
  ]
}

Webhook Payload

{
  "event": "session.started",
  "timestamp": "2026-04-15T14:00:00Z",
  "communityId": "expo-2026",
  "data": {
    "sessionId": "ses_abc123",
    "title": "Building Products That Scale",
    "mode": "ama",
    "hostIds": ["usr_sarah"],
    "participantCount": 34
  }
}