Public APIv1

ASKTC Documentation

Guides for the API, the realtime connection and webhooks, then the full reference. The API is REST-based, returns JSON, and uses API key authentication.

Base URLhttps://asktc.live/api/v1

Overview

API Key Auth

All requests require a Bearer token in the Authorization header.

REST + JSON

Standard HTTP methods. All responses are JSON.

AI-powered

Create events from plain English, cluster questions, and analyse sentiment.

Real-time ready

Changes you make through the API reach every screen in the room as they happen.

Quickstart

Create an event, take a question and moderate it in about five minutes. You need a Pro or Enterprise plan for the API; the same things work in the dashboard on every plan.

  1. Create a key in Developers / API keys. Keys start with aktc_.
  2. Create an event. The response has the event code your audience joins with.
  3. Submit a question, then approve it. Approved questions reach every phone and the projector.
bash
export ASKTC_KEY=aktc_your_api_key_here
BASE=https://asktc.live/api/v1

# 1. Create an event
curl -X POST $BASE/events \
  -H "Authorization: Bearer $ASKTC_KEY" -H "Content-Type: application/json" \
  -d '{"title": "DevDay Lagos 2026", "event_code": "DEVDAY26"}'

# 2. Send a question (it waits for approval by default)
curl -X POST $BASE/events/DEVDAY26/questions \
  -H "Authorization: Bearer $ASKTC_KEY" -H "Content-Type: application/json" \
  -d '{"content": "How do we get a team plan?", "asked_by": "Ada"}'

# 3. See what is waiting, then approve one by id
curl "$BASE/events/DEVDAY26/questions?status=pending" -H "Authorization: Bearer $ASKTC_KEY"
curl -X PATCH $BASE/events/DEVDAY26/questions/QUESTION_ID \
  -H "Authorization: Bearer $ASKTC_KEY" -H "Content-Type: application/json" \
  -d '{"status": "approved"}'

The same calls from JavaScript:

bash
const BASE = 'https://asktc.live/api/v1'
const headers = { Authorization: `Bearer ${process.env.ASKTC_KEY}`, 'Content-Type': 'application/json' }

const ask = await fetch(`${BASE}/events/DEVDAY26/questions`, {
  method: 'POST', headers, body: JSON.stringify({ content: 'How do we get a team plan?', asked_by: 'Ada' }),
}).then((r) => r.json())

await fetch(`${BASE}/events/DEVDAY26/questions/${ask.question.id}`, {
  method: 'PATCH', headers, body: JSON.stringify({ status: 'approved' }),
})
Prefer to talk to an assistant? Connect the MCP server and run the same steps in plain language.

Concepts

The few ideas the rest of the docs build on.

TermWhat it is
EventOne session with a join code (4 to 16 letters and digits). The code is also the realtime room name, in lower case.
Event statuswaiting, then live, then ended. Phones can ask while it is live; an async event also takes questions before and after.
QuestionWhat the audience sends. It has a status, a vote count and, once answered, an answer.
Rolesaudience (phones), display (projector and wall), moderator (the owner and invited moderators), panelist and presenter.
RoomThe live copy of an event that screens connect to. Everything an audience can see travels through it.

Question statuses

StatusWho sees itMeaning
pendingHosts onlyWaiting for a moderator, or held by a rule or the AI check.
approvedEveryoneIn the audience queue, and open for votes.
on_screenEveryoneShown on the projector right now.
answeredEveryoneDone. It carries answer_text if one was written.
ask_laterHosts onlyParked by the moderator for later.
rejectedHosts onlyRemoved from the audience view.

Plans and limits

FreeEvent passProEnterprise
Events1 at a time1UnlimitedUnlimited
Questions per event100500UnlimitedUnlimited
Audience size505005,000Unlimited
API and webhooksNoNoYesYes
Before and after questions (async)NoNoYesYes
CSV exportNoNoYesYes
Custom brandingNoNoNoYes

Moderation, panelists, breakout rooms, AI clustering, reactions and the word cloud are on every plan. See pricing for prices.

Realtime

Every screen in a room, phones, projector, wall and the moderator, listens on one WebSocket to our realtime service. You can connect to it yourself, for example to build a custom stage display.

Connect

bash
wss://flyingfish-asktc.fly.dev/rooms/{eventCode in lower case}/ws?role=display
roleCanNeeds
audienceReceive everything the audience sees. Send reactions.Nothing
displayReceive only. For projector and wall style screens.Nothing
moderator, panelistReceive, and send host-to-host messages (pointer, drawing, captions).A short-lived signed pass from your signed-in session. Not available to API keys.

A public socket only ever receives what an audience member may see. Pending and rejected questions, asker emails and answer keys are never sent to it.

Frames from the server

typePayloadNotes
broadcast{ event, data }A change in the room. See the event table below.
presence_count{ total, by_role }Sent on connect. by_role.audience is the number of phones (host screens are not counted).
presence_diff{ by_role, delta }Sent as people join and leave. Use by_role when it is there, not the delta.
reaction_batch{ counts }Emoji reactions grouped over a moment, such as { "πŸ”₯": 12 }. Draw a few floaters per emoji, not one per tap.
replayrecent messagesMay follow a connect. Ignore it and read the snapshot instead: a replayed message can be older than the snapshot.
draining(none)The server is restarting. Close and reconnect straight away.

Send {"type":"ping"} every 15 seconds. The server answers with a pong, and drops a client that has said nothing for 90 seconds, so a ghost never counts as a person in the room. If your own ping gets no answer within about 8 seconds, treat the socket as dead and reconnect: a phone that loses signal often never closes the connection. An audience client sends a reaction as {"type":"react","payload":{"emoji":"πŸ”₯"}}.

Events you will see in broadcast

eventdata
question:new{ question } for a question that is approved. Held questions are not sent.
question:update{ question }, or { id, status } when a question leaves public view. Remove it from your list on any non-public status.
question:votes{ questionId, votes }: the full count, not an increment.
question:tags{ questionId, tagIds, createdTags, source }
question_answering{ questionId, is_answering, panelistName? }
question_answered{ questionId, answer_text }
poll:updateA poll opened, changed or closed, with its options.
poll:counts{ pollId, votes } where votes is the full list of counts.
adv_poll:activate, adv_poll:update, adv_poll:countsThe same for ranking, scale, matrix and image polls. counts is the full total.
wordcloud:toggle, wordcloud:count{ active, counts } when the cloud is switched, then { word, count } as words arrive.
thread:activate, thread:close, thread:answerThread Mode. While a timed question runs, an answer arrives sealed, with no text.
quiz:activate, quiz:closeA quiz question opened or closed. Correct answers are never included.
event_live, event_endedThe event changed state.
slide_change, screen_blank, layout_change, projector_mode, timer_start, timer_stopStage controls from the presenter and moderator.

Keeping a screen correct

  • Counts are totals. Votes, poll results and word counts always carry the full number, so a repeated or late message cannot move a count backwards. Replace, never add.
  • Messages arrive in order. Each client has its own queue, so a later count can never overtake an earlier one. A client that falls 256 messages behind is cut off; it reconnects and reads the snapshot.
  • Messages can arrive twice. Each carries a _mid. Remember the last few hundred and drop repeats.
  • Start from the snapshot. GET https://asktc.live/api/live/room/{CODE} returns the room as an audience sees it: the event, approved questions, polls with counts, the word cloud and tags. It is cached for about 3 seconds, so you can call it freely.
  • Reconnect fast, then back off. A connection that was working comes straight back after about 150 ms; later tries wait half a second, growing to 15 seconds, with random jitter. Reconnect at once when the tab becomes visible or the network returns. After a reconnect, fetch the snapshot again, because you may have missed messages.
  • If the socket is down, poll the snapshot every 8 to 12 seconds. Phones do exactly this.
bash
const code = 'devday26'
const seen = new Set()
let counts = {}

async function load() {
  const room = await fetch(`https://asktc.live/api/live/room/${code}`).then((r) => r.json())
  // render room.questions, room.pollVotes, room.wordCounts ...
}

function open(attempt = 0) {
  const ws = new WebSocket(`wss://flyingfish-asktc.fly.dev/rooms/${code}/ws?role=display`)
  const ping = setInterval(() => ws.readyState === 1 && ws.send(JSON.stringify({ type: 'ping' })), 15000)
  ws.onopen = () => { attempt = 0; load() }
  ws.onmessage = (e) => {
    const msg = JSON.parse(e.data)
    if (msg.type === 'draining') return ws.close()
    if (msg.type !== 'broadcast') return
    const { event, data } = msg.payload
    if (data?._mid) { if (seen.has(data._mid)) return; seen.add(data._mid) }
    if (event === 'question:votes') counts[data.questionId] = data.votes   // replace, never add
    // handle the other events you draw
  }
  ws.onclose = () => { clearInterval(ping); setTimeout(() => open(attempt + 1), Math.min(15000, 500 * 1.5 ** attempt) * (0.7 + Math.random() * 0.6)) }
}
open()

The realtime service held 10,000 phones in one room in our load test, and a message reached all of them in under half a second. Changes you make through the API reach connected screens the same way.

Verify a webhook

Every delivery is signed with the secret you received when you registered the endpoint. Check the signature before you trust the body.

The X-ASKTC-Signature header is the hex HMAC-SHA256 of the raw request body. Compute it over the bytes you received, before any JSON parsing.

bash
import crypto from 'node:crypto'
import express from 'express'

const app = express()

app.post('/asktc', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto.createHmac('sha256', process.env.ASKTC_WEBHOOK_SECRET).update(req.body).digest('hex')
  const got = String(req.get('X-ASKTC-Signature') || '')
  const ok = got.length === expected.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))
  if (!ok) return res.sendStatus(401)

  const payload = JSON.parse(req.body.toString('utf8'))
  if (payload.event === 'question.created') {
    // payload.data.question.id, .content, .status
  }
  res.sendStatus(200)
})
bash
import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post('/asktc')
def asktc():
    raw = request.get_data()
    expected = hmac.new(os.environ['ASKTC_WEBHOOK_SECRET'].encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(request.headers.get('X-ASKTC-Signature', ''), expected):
        abort(401)
    payload = request.get_json()
    return '', 200
Deliveries are best effort with a 5 second timeout and no retries. Answer quickly with a 2xx, and use GET /events/:code/questions?since= to catch up on anything you missed.

API reference

Every endpoint, with parameters and examples.

Authentication

All API requests must include your API key as a Bearer token in the Authorization header. API keys start with aktc_. API access needs a Pro or Enterprise plan; the free plan gets a 403.

bash
curl https://asktc.live/api/v1/events \
  -H "Authorization: Bearer aktc_your_api_key_here"
Get your API key from the Developers / API keys.

Connecting via Claude.ai or another OAuth-aware MCP client?You don't need an API key at all β€” add https://asktc.live/api/mcp as a custom connector and it authorizes over OAuth 2.1 (PKCE, dynamic client registration, and MCP Client ID Metadata Documents are all supported). ASKTC exposes standard discovery metadata so compatible clients configure themselves:

GET
/.well-known/oauth-authorization-server

Authorization server metadata (RFC 8414) β€” issuer, authorization/token/registration endpoints.

GET
/.well-known/oauth-protected-resource

Protected resource metadata (RFC 9728) for the MCP endpoint.

POST
/register

Dynamic Client Registration (RFC 7591) for public clients, e.g. Claude.ai. No auth required.

GET
/authorize

Consent screen. Requires response_type=code, client_id, redirect_uri, code_challenge (S256).

resourcestring

Optional (RFC 8707). If sent, it must be https://asktc.live/api/mcp β€” bound to the issued token and re-checked at /token.

POST
/token

Exchanges an authorization code (or refresh_token) for an access token. PKCE required, no client_secret.

Issued access tokens work exactly like an API key against every endpoint on this page and the MCP server β€” they're minted from the same underlying store. Revoke them anytime from Developers / API keys.

Prefer talking to your AI agent instead?

ASKTC has a native MCP server β€” connect Claude, Cursor, or Windsurf and manage events from a conversation.

View MCP

Giving ASKTC to an AI agent?

Point it at asktc.live/agent-ready.md. It explains how to connect, how to run an event end to end, and the rules an agent should follow in a live room. Paste this into your agent:

text
Read https://asktc.live/agent-ready.md and set me up with ASKTC. First ask me whether I want to
(a) run an event, (b) try it safely on a throwaway event, or (c) read results from an existing event.
Follow the "Rules for agents" section exactly. Never delete or end anything without asking me first.

Rate Limits

Rate limits are enforced per API key using a sliding window. When exceeded, the API returns 429 Too Many Requests.

PlanPer minutePer day
Pro30010,000
Enterprise1,000Unlimited
AI endpoints10 (all plans)β€”

Rate limit headers are returned on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Events

GET
/events

List all events owned by the authenticated user.

POST
/events

Create a new event.

titlestringrequired

The event title. Max 100 characters.

event_codestring

Custom join code (4–16 chars, A–Z 0–9). Auto-generated if omitted.

session_modeenum

One of panel, open_floor, thread. Defaults to panel.

descriptionstring

Optional event description. Max 500 characters.

is_asyncboolean

Enable async mode β€” the event accepts questions before and after the live session ends. Defaults to false.

async_closes_atISO 8601 string

Optional deadline for async submissions. Null = no deadline. Only relevant when is_async is true.

bash
curl -X POST https://asktc.live/api/v1/events \
  -H "Authorization: Bearer aktc_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "DevDay Lagos 2026", "session_mode": "panel", "event_code": "DEVDAY26"}'
GET
/events/:code

Fetch a single event by event code.

PATCH
/events/:code

Update title, description, session_mode, or async settings. Ended events may only change is_async / async_closes_at.

is_asyncboolean

Enable or disable async collection outside the live window.

async_closes_atISO 8601 string | null

Deadline for async submissions, or null to clear.

DELETE
/events/:code

Permanently delete an event and all associated data.

PATCH
/events/:code/schedule

Set or clear the scheduled start time for an event.

scheduled_atISO 8601 string

Set to a future datetime to schedule, or null to clear.

Questions

GET
/events/:code/questions

Fetch the questions for an event, ordered by vote count. Includes answer_text and answered_episode when set. The asker's email is never returned.

statusenum

Only return questions with this status: pending, approved, on_screen, answered, rejected or ask_later.

sinceISO 8601 string

Only return questions created after this time. Handy for polling during a live event.

limitnumber

Page size. Defaults to 50, maximum 200.

offsetnumber

Number of questions to skip. Defaults to 0.

The response is { questions, total, limit, offset }, where total counts every match, not just this page. Unlike the audience, the API returns questions in every status, including pending and rejected.

POST
/events/:code/questions

Submit a question programmatically β€” agents, bots, Zapier. Works while live or while async collection is still open (deadline respected). New questions reach the room live once they are approved; a question waiting for approval is shown only to you and your moderators.

contentstringrequired

The question text. Max 500 characters.

asked_bystring

Display name shown to the audience. Defaults to Anonymous.

emailstring

Asker's email address. If provided, they get a notification when their question is answered. It is stored privately: only you and your moderators can see it, and the API never returns it.

sourcestring

Origin of the question β€” text | telegram | whatsapp. Defaults to text.

statusstring

pending (default) or approved to auto-approve on submit. Your moderation rules have the final say: a rule can make the outcome stricter than what you asked for, never looser.

If the question is a near-duplicate of one already asked, it is merged into that question as a vote instead of being created. The response then has merged: true with the existing question_id and its new vote count. A question blocked by a moderation rule returns 400 with the reason.

PATCH
/events/:code/questions/:id

Moderate a question β€” approve, reject, mark answered, or push to the projector (agents can drive on_screen).

statusenum

One of pending, approved, on_screen (projector β€” demotes any previous on-screen question), answered, rejected, ask_later.

answer_textstring

Written answer. Sets status to answered when provided alone.

answered_episodestring

Podcast label, e.g. Episode 47. Included in the asker email when you notify them.

starredboolean

Star or unstar the question.

GET
/events/:code/questions/clusters

AI-powered β€” group semantically similar questions into clusters. Useful for surfacing themes across hundreds of submissions.

Embed Widget

Drop a live Q&A question box onto any website with a single script tag β€” no API key required. Questions submitted through the embed land in your moderator queue exactly like audience submissions from the ASKTC room.

html
<!-- Paste this where you want the widget to appear -->
<script src="https://asktc.live/embed.js?code=DEVDAY26"></script>
codestringrequired

Your event join code. The widget uses this to route submissions.

heightnumber

Iframe height in pixels. Defaults to 520.

widthstring

Iframe width. Accepts px or %. Defaults to 100%.

The widget iframe is served from /embed/:code and accepts questions on events that are live or in async mode. It is CORS-open β€” safe to embed on any domain.

Questions submitted via the embed are marked pending and go through the same moderation flow as audience submissions. Enable async mode on your event to keep accepting embed submissions after the live session ends.

The embed UI includes Top questions (ranked + upvote) and Ask tabs β€” same engine as the room and hosted show page. Optional query theme=dark on the embed URL for dark surfaces.

Show Pages

Hosted show notes for podcasters who do not have a website: https://asktc.live/p/{slug}. Listeners ask and upvote via the same ranking widget as the embed. Optional episode archive lists past shows.

GET
/p/:slug

Public HTML show page (not JSON). Renders show profile, linked async collect (embed), and episode list.

Host setup is in the dashboard (Show page) β€” session cookie auth, not the API key. Management endpoints:

GET
/api/shows/me

Session auth. Returns the authenticated host’s show row (slug, title, active_event_id, …).

PUT
/api/shows/me

Session auth. Upsert show page. One show per account; slugs are globally unique.

titlestringrequired

Show display name.

slugstringrequired

URL segment, a-z 0-9 hyphens. A taken slug returns 409.

taglinestring

Short subtitle.

descriptionstring

About blurb.

active_event_iduuid

Event to collect on β€” prefer async.

GET
/api/shows/me/episodes

Session auth. List episodes for the host’s show.

POST
/api/shows/me/episodes

Session auth. Pro/Enterprise only (402 on Free). Add an episode to the public archive.

titlestringrequired

Episode title.

episode_labelstring

e.g. Episode 47.

summarystring

Short notes.

external_urlstring

Spotify / Apple / YouTube link.

DELETE
/api/shows/me/episodes?id=

Session auth. Delete one episode by id.

Agents moderating podcast Q&A still use the v1 key on PATCH /events/:code/questions/:id with answered_episode. Show page CRUD is host-dashboard only for now.

Panelists

GET
/events/:code/panelists

List all panelists for an event.

POST
/events/:code/panelists

Add a panelist to an event.

namestringrequired

Panelist full name.

titlestring

Job title or role.

topicsstring

Comma-separated topics this panelist covers.

PATCH
/events/:code/panelists?id=

Update a panelist's name, title, or topics. Useful for correcting AI-extracted panelist details.

namestring

Updated display name.

titlestring

Updated role/title. Pass null to clear.

topicsstring

Updated comma-separated topics. Pass null to clear.

DELETE
/events/:code/panelists?id=

Remove a panelist from an event.

Moderators

GET
/events/:code/moderators

List all co-moderators for an event.

POST
/events/:code/moderators

Invite a co-moderator. The account must already exist on ASKTC β€” an invite email is sent automatically if email is configured.

emailstringrequired

ASKTC account email of the person to add.

roleenum

One of moderator, viewer. Defaults to moderator.

DELETE
/events/:code/moderators?id=

Remove a co-moderator from an event. The event owner cannot be removed.

Tags

Tags label questions by topic β€” the dashboard's AI auto-tagger and filter chips both key off this table.

GET
/events/:code/tags

List all tags for an event.

POST
/events/:code/tags

Create a tag.

namestringrequired

Tag label, e.g. "Pricing".

colorstring

Hex color, e.g. #6366f1. Defaults to a preset.

DELETE
/events/:code/tags?id=

Delete a tag. Any questions tagged with it lose that tag.

Audience Segments

Give a group (VIP, Press, Staff) its own join link. Their questions land in the same queue, tagged by segment so moderators can filter by group.

GET
/events/:code/segments

List all audience segments for an event, including each one's join_url.

POST
/events/:code/segments

Create an audience segment.

namestringrequired

Segment label, e.g. "VIP".

colorstring

Hex color, e.g. #6366f1. Defaults to a preset.

DELETE
/events/:code/segments?id=

Delete an audience segment. Already-tagged questions keep their history; the segment association is cleared.

Polls

GET
/events/:code/polls

List all polls for an event, including live vote counts per option.

statusstring

Filter by status β€” draft | active | closed.

POST
/events/:code/polls

Create a poll. Set status to 'active' to launch it immediately β€” any currently active poll will be closed automatically.

questionstringrequired

The poll question.

optionsstring[]required

At least 2 answer options, max 10.

option_imagesstring[]

Parallel array of image URLs, one per option β€” turns this into an image-choice poll. Upload images to your own host first (the dashboard uploads to ASKTC's own storage automatically; via the API you supply the URLs).

statusstring

draft (default) or active to launch immediately.

is_quizboolean

Enable quiz mode with a correct answer. Defaults to false.

correct_optionnumber

0-based index of the correct option. Required when is_quiz is true.

PATCH
/events/:code/polls?id=

Update a poll's status β€” launch, close, or revert to draft. Reaches every screen live.

statusstringrequired

draft | active | closed.

DELETE
/events/:code/polls?id=

Delete a poll and all its votes.

Breakout Rooms

GET
/events/:code/breakout

List all breakout rooms for an event.

POST
/events/:code/breakout

Create a breakout room.

namestringrequired

Room name.

capacitynumber

Max participants. Defaults to your plan's audience cap (50 Free, 500 Event Pass, 5,000 Pro).

PATCH
/events/:code/breakout?id=

Update a breakout room's name or capacity.

DELETE
/events/:code/breakout?id=

Delete a breakout room.

AI

AI endpoints are rate-limited to 10 requests per minute across all plans.
POST
/ai/create-event

Create a fully structured event from a natural language prompt. AI picks session mode, detects async/podcast collection, optional deadline, and named panelists.

promptstringrequired

Plain English description (max 1000 chars). Say β€œpodcast”, β€œcollect over a week”, or similar to enable is_async.

event_codestring

Override the AI's suggested join code.

dry_runboolean

If true, returns the AI plan without creating anything. Use to preview before committing.

bash
curl -X POST https://asktc.live/api/v1/ai/create-event \
  -H "Authorization: Bearer aktc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A fintech panel at Lagos Tech Week with Ada Obi covering regulation and Emeka Nwosu on infrastructure",
    "dry_run": false
  }'
json
{
  "event": {
    "id": "evt_...",
    "title": "Lagos Tech Week β€” Fintech Panel",
    "event_code": "LAGOSTECHWK",
    "session_mode": "panel",
    "status": "waiting",
    "is_async": false,
    "async_closes_at": null,
    "created_at": "2026-08-02T10:00:00Z"},
  "panelists": [
    { "id": "p_...", "name": "Ada Obi",    "title": null, "topics": "regulation"},
    { "id": "p_...", "name": "Emeka Nwosu","title": null, "topics": "infrastructure"}
  ],
  "plan": {
    "reasoning": "Named panelists detected; panel mode selected.",
    "suggested_event_code": "LAGOSTECHWK"},
  "dry_run": false
}

Reports & Analytics

GET
/events/:code/report

Full event summary β€” questions, polls, answer counts, top voted, participation stats.

POST
/events/:code/report/send

Email the event report to the host and any specified recipients.

emailsstring[]

Additional recipient emails beyond the host.

GET
/events/:code/sentiment

Aggregated sentiment breakdown across all audience questions β€” positive, neutral, negative percentages with top themes.

Thread Questions

For events in thread mode: the host asks one question at a time and the audience answers it. Only one thread question can be live per event.

GET
/events/:code/thread-questions

List thread questions in queue order.

statusenum

pending | active | closed.

POST
/events/:code/thread-questions

Create a thread question. It starts as pending until you activate it.

bodystringrequired

The question text.

positionnumber

Place in the queue. Defaults to the end.

max_answersnumber

Close automatically after this many answers.

time_limitnumber

Close automatically after this many seconds live. Only enforced while a moderator has the control room open; otherwise close it with the endpoint below.

correct_answersstring[]

Accepted answers. Each audience answer is checked against them and marked correct automatically when it matches exactly or nearly (small typos, a sentence around the answer). Leave out for an open question. The accepted answers are never shown to the audience.

PATCH
/events/:code/thread-questions/:id

Edit the text, position, max_answers, time_limit or correct_answers. Pass null to clear a limit, or an empty list to clear the accepted answers.

DELETE
/events/:code/thread-questions/:id

Delete a thread question and all its answers.

POST
/events/:code/thread-questions/:id/activate

Push it live. Any other active thread question is closed first, and every screen updates immediately.

POST
/events/:code/thread-questions/:id/close

Close the live question early. Returns 400 if it is not active.

GET
/events/:code/thread-questions/:id/answers

List the answers, oldest first, with asked_by and is_anonymous. Whether an answer matched is shown live in the room; ai_score and ai_feedback are no longer filled in. Answers a host has hidden are still returned to you.

Moderation Rules

GET
/events/:code/moderation-rules

List the rules for an event, including global rules that apply to it.

POST
/events/:code/moderation-rules

Create a rule. Rules run on every new question, whether it comes from the room, the API or the embed.

rule_typeenumrequired

keyword_ban | pattern_regex | duplicate_detection | length_limit | rate_limit | profanity_filter

rule_namestringrequired

A label for your own reference.

rule_valuestringrequired

What the rule checks: the word list, the pattern, or the limit.

severityenumrequired

low | medium | high

actionenumrequired

flag | auto_reject | auto_quarantine

is_activeboolean

Defaults to true.

PATCH
/events/:code/moderation-rules?id=

Change any field of a rule. Global rules cannot be edited.

DELETE
/events/:code/moderation-rules?id=

Delete a rule. Global rules cannot be deleted.

Autopilot

PATCH
/events/:code/autopilot-settings

Change autopilot settings. Fields you leave out keep their current value.

enabledboolean

Master on/off.

modeenum

mechanical (approves on a quality score) or cohost (acts with more judgement).

quality_thresholdnumber

0 to 1. Mechanical mode only approves above this score.

confidence_floornumber

0 to 1. Cohost mode hands the decision to a human below this.

max_actions_per_minnumber

Cap on autonomous actions per minute in cohost mode.

push_delay_secondsnumber

Wait before pushing a question to the screen.

screen_time_secondsnumber

How long a question stays on screen.

GET
/events/:code/autopilot-log

What autopilot did and why, newest first.

limitnumber

Defaults to 50, maximum 200.

Webhooks

ASKTC sends a signed POST to your URL when something happens in the event. Today that is question.created. Delivery is best effort with a 5 second timeout and no retries, so treat the API as the source of truth.

GET
/events/:code/webhooks

List your endpoints. The secret is never shown again.

POST
/events/:code/webhooks

Register an endpoint. The response includes its secret once. Save it.

urlstringrequired

Must be https.

PATCH
/events/:code/webhooks?id=

Change the url or pause delivery with is_active.

DELETE
/events/:code/webhooks?id=

Remove an endpoint.

Each delivery carries X-ASKTC-Event and X-ASKTC-Signature, the hex HMAC-SHA256 of the raw body using your secret. Check it before trusting the request.

json
{
  "event": "question.created",
  "event_id": "…",
  "data": { "question": { "id": "…", "content": "…", "status": "pending"} },
  "timestamp": "2026-10-20T10:00:00.000Z"}

Privacy

What the audience sees. Only approved, on-screen and answered questions reach audience phones. Pending and rejected questions are visible to you and your moderators only, in the API and in live updates.

Asker details. The asker's email and device fingerprint are stored apart from the question. Only you and your moderators can read them, and the API never returns them.

Live updates. Votes, poll results and word-cloud counts are sent as full totals, so a late or repeated message can never move a number backwards. Changes you make through the API reach every screen as they happen.

How updates reach the room. Phones, projectors and walls hold one live connection and receive changes within about a second. If that connection is unavailable, they fall back to the database automatically, so the room keeps working, only a little slower. To watch an event from code, poll the questions endpoint with since.

Replay. The replay timeline for an ended event only shows what the audience could see at the time. Unapproved questions are left out.

Errors

All errors return a JSON object with an error field.

StatusMeaning
400Bad Request β€” missing or invalid parameters.
401Unauthorized β€” missing or invalid API key.
403Forbidden β€” your plan doesn't support this endpoint.
404Not Found β€” event or resource doesn't exist.
409Conflict β€” event code already taken.
429Too Many Requests β€” rate limit exceeded.
500Internal Server Error β€” something went wrong on our end.
502Bad Gateway β€” AI service unavailable.
json
{
  "error": "Event code \"DEVDAY26\" is already taken. Pass a custom event_code or omit it to auto-generate."}

ASKTC API v1 · Built with 🧑 in Nigeria