Ask a question about an event

POST/v1/event/{eventId}/ask

US Region: https://public-api.sessionboard.com · EU Region: https://public-api-eu.sessionboard.com

Ask a question about one event in plain language and get an answer written for the organizer. The answer is grounded in the event's program (sessions, speakers, exhibitors, sponsors), session transcripts, the event's knowledge and pinned answers, and the Sessionboard Help Center. [n] markers in answer point at citations[] entry index n; citations are built from records, never from model text.

Read-only: nothing in the event changes and actions is always [].

Requires the read:ask scope, granted explicitly — a legacy token with an empty scope list does not get it. The token's event allow-list and the organization's AI features switch apply.

Slow. An answer takes several seconds and can take up to 90; set your client timeout to at least 90 seconds. If Sessionboard does not answer in time the API returns 504.

To ask a follow-up in the same thread, send back the conversation_id from the previous answer. A conversation continues only for the same token and user; any other conversation_id starts a new conversation.

The API request log records the call with question redacted.

Request example

curl --request POST \
  --url 'https://public-api.sessionboard.com/v1/event/{eventId}/ask' \
  --header 'x-access-token: <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "question": "Which sessions on Tuesday cover AI?",
  "lang": "en"
}'

const response = await fetch('https://public-api.sessionboard.com/v1/event/{eventId}/ask', {
  method: 'POST',
  headers: {
    "x-access-token": "<api-token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "question": "Which sessions on Tuesday cover AI?",
    "lang": "en"
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.request(
    "POST",
    "https://public-api.sessionboard.com/v1/event/{eventId}/ask",
    headers={
        "x-access-token": "<api-token>",
        "Content-Type": "application/json"
    },
    json={
        "question": "Which sessions on Tuesday cover AI?",
        "lang": "en"
    },
)

print(response.json())

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://public-api.sessionboard.com/v1/event/{eventId}/ask",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => '{
  "question": "Which sessions on Tuesday cover AI?",
  "lang": "en"
}',
    CURLOPT_HTTPHEADER => [
        "x-access-token: <api-token>",
        "Content-Type: application/json",
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
  "fmt"
  "io"
  "net/http"
  "strings"
)

func main() {
  req, _ := http.NewRequest("POST", "https://public-api.sessionboard.com/v1/event/{eventId}/ask", strings.NewReader(`{
  "question": "Which sessions on Tuesday cover AI?",
  "lang": "en"
}`))
  req.Header.Add("x-access-token", "<api-token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://public-api.sessionboard.com/v1/event/{eventId}/ask"))
    .header("x-access-token", "<api-token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"question\": \"Which sessions on Tuesday cover AI?\",\n  \"lang\": \"en\"\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

Try it

Response headers

Authorizations

x-access-tokenstringheader
Organization API token. Generate from Organization Settings → API Tokens.
AuthorizationBearer <token>headeror
OAuth 2.1 access token. Obtained via the OAuth PKCE flow at /oauth/token.

Send one of these. See Authentication.

Path parameters

eventIdintegerpathrequired
The event to ask about.

Request body

application/jsonrequired

questionstringrequired
The question, in plain language. Whitespace is collapsed before the length check: under 2 or over 500 characters returns 422 (empty / too_long), and a value over 1000 characters is rejected with 400.
Min length
2
Max length
500
conversation_idstring<uuid>
The conversation_id from a previous answer, to ask a follow-up in the same thread.
langstring
Answer language as a language tag, e.g. en, fr, pt-BR.
Max length
16
Pattern
^[A-Za-z]{2,3}([-_][A-Za-z0-9]{2,8})?$

Example

{
  "question": "Which sessions on Tuesday cover AI?",
  "lang": "en"
}

Responses

200`application/json`

The answer and its sources.

statusstringrequired
Allowed values
"ok"
answerstringrequired
The answer as Markdown. [n] marks citation n.
citationsAskCitation[]required
Show child attributes
- indexintegerrequired
  The n in the answer's [n] marker.
- typestringrequired
  Allowed values
  "session", "speaker", "exhibitor", "sponsor", "product", "poster", "room", "pin", "info", "transcript", "doc", "pinned", "help"
- idstringrequired
  The id of the cited record.
- titlestring
- namestring
- starts_atstring<date-time>
- session_idstring
- session_titlestring
- start_msinteger
  Offset into the session recording, for a transcript excerpt.
- textstring
  The quoted passage, for a transcript excerpt.
actionsany[]required
Always empty — this endpoint is read-only.
Max items
0
conversation_idstring<uuid>required
Send this back with a follow-up question to continue the conversation.
message_idstring<uuid>required
The id of this answer.

RateLimit-Limitintegerheader
Requests allowed in the current window.
RateLimit-Remainingintegerheader
Requests left in the current window.

400

Malformed body: question missing, an unknown key, a conversation_id that is not a UUID, a lang that is not a language tag, or a question longer than 1000 characters.

401

Missing, invalid, revoked or expired token.

403`application/json`

SCOPE_REQUIRED — the token does not hold read:ask (legacy tokens with no scopes included).
EVENT_NOT_ALLOWED — the event is outside the token's event allow-list.
AI_DISABLED — AI features are switched off for the organization.
FORBIDDEN — Ask is switched off for this event (details.reason: off), AI features are off (details.reason: ai_disabled), or the organization is out of AI credits under enforcement (details.reason: ai_credits).

errorstringrequired
Allowed values
"VALIDATION_ERROR", "SCOPE_REQUIRED", "EVENT_NOT_ALLOWED", "AI_DISABLED", "FORBIDDEN", "RATE_LIMITED", "QUOTA_EXCEEDED", "INTERNAL_ERROR"
messagestring
detailsobject
reason, and for RATE_LIMITED also retry_after_seconds and remaining_today.
Show child attributes
- reasonstring
  Allowed values
  "empty", "too_long", "blocked", "repeated", "per_minute", "daily", "busy", "off", "ai_disabled", "ai_credits"
- retry_after_secondsinteger
- remaining_todayinteger

404

The event does not exist or belongs to another organization.

422`application/json`

VALIDATION_ERROR — Ask would not take the question. Nothing is spent. details.reason is empty (under 2 characters), too_long (over 500 characters), blocked (flagged as unsafe) or repeated (the same question asked twice in a row).

errorstringrequired
Allowed values
"VALIDATION_ERROR", "SCOPE_REQUIRED", "EVENT_NOT_ALLOWED", "AI_DISABLED", "FORBIDDEN", "RATE_LIMITED", "QUOTA_EXCEEDED", "INTERNAL_ERROR"
messagestring
detailsobject
reason, and for RATE_LIMITED also retry_after_seconds and remaining_today.
Show child attributes
- reasonstring
  Allowed values
  "empty", "too_long", "blocked", "repeated", "per_minute", "daily", "busy", "off", "ai_disabled", "ai_credits"
- retry_after_secondsinteger
- remaining_todayinteger

429`application/json`

RATE_LIMITED — the per-user question limit (by default 10 a minute and 200 a day). details.reason is per_minute or daily; wait Retry-After seconds (also details.retry_after_seconds).
QUOTA_EXCEEDED — the event's daily Ask budget is used up (details.reason: busy). Try again later.
The API's own limit of 100 requests per 15 minutes per token, and 20 requests a minute per organization and user, also return 429 with Retry-After. That body is the gateway's TooManyRequestsError shape (name, message, status, success), not an AskError — see Rate Limiting.

responseAskError | TooManyRequestsError
Option 1 (AskError)
- errorstringrequired
  Allowed values
  "VALIDATION_ERROR", "SCOPE_REQUIRED", "EVENT_NOT_ALLOWED", "AI_DISABLED", "FORBIDDEN", "RATE_LIMITED", "QUOTA_EXCEEDED", "INTERNAL_ERROR"
- messagestring
- detailsobject
  reason, and for RATE_LIMITED also retry_after_seconds and remaining_today.
  Show child attributes
  - reasonstring
    Allowed values
    "empty", "too_long", "blocked", "repeated", "per_minute", "daily", "busy", "off", "ai_disabled", "ai_credits"
  - retry_after_secondsinteger
  - remaining_todayinteger
name: TooManyRequestsError (TooManyRequestsError)
Body of a 429 from the API's own request limits (per token, and per organization and user). Wait Retry-After seconds.
- statusinteger
  Example
  429
- successboolean
  Example
  false
- messagestringrequired
  Example
  "Error while trying to reach the endpoint: Too many requests"
- namestringrequired
  Allowed values
  "TooManyRequestsError"

Retry-Afterintegerheader
Seconds to wait before asking again.

500`application/json`

INTERNAL_ERROR — Ask could not answer right now. Retry later.

errorstringrequired
Allowed values
"VALIDATION_ERROR", "SCOPE_REQUIRED", "EVENT_NOT_ALLOWED", "AI_DISABLED", "FORBIDDEN", "RATE_LIMITED", "QUOTA_EXCEEDED", "INTERNAL_ERROR"
messagestring
detailsobject
reason, and for RATE_LIMITED also retry_after_seconds and remaining_today.
Show child attributes
- reasonstring
  Allowed values
  "empty", "too_long", "blocked", "repeated", "per_minute", "daily", "busy", "off", "ai_disabled", "ai_credits"
- retry_after_secondsinteger
- remaining_todayinteger

504

No answer within 90 seconds. Retry, or ask a narrower question.

Response examples

{
  "status": "ok",
  "answer": "Two sessions on Tuesday cover AI [1] [2].",
  "citations": [
    {
      "index": 1,
      "type": "session",
      "id": "3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f",
      "title": "Applied AI in Clinical Practice",
      "starts_at": "2026-11-10T14:00:00.000Z"
    },
    {
      "index": 2,
      "type": "session",
      "id": "8d1e4b2a-6c3f-4a9e-b7d0-2e3f4a5b6c7d",
      "title": "Panel: Where AI Helps and Where It Hurts",
      "starts_at": "2026-11-10T16:30:00.000Z"
    }
  ],
  "actions": [],
  "conversation_id": "7b0c0e0c-9a39-4b8f-9d5d-1e2f3a4b5c6d",
  "message_id": "2c9e7a41-0b3d-4f6e-8a1c-5d4e3f2a1b0c"
}

{
  "error": "SCOPE_REQUIRED",
  "message": "This operation requires the 'read:ask' scope."
}

{
  "error": "EVENT_NOT_ALLOWED",
  "message": "This API token is not allowed to access this event"
}

{
  "error": "AI_DISABLED",
  "message": "AI features are not enabled for this organization"
}

{
  "error": "FORBIDDEN",
  "message": "Ask is switched off for this event.",
  "details": {
    "reason": "off"
  }
}

{
  "error": "FORBIDDEN",
  "message": "Out of AI credits. Add credits to continue.",
  "details": {
    "reason": "ai_credits"
  }
}

{
  "error": "VALIDATION_ERROR",
  "message": "Ask could not take that question.",
  "details": {
    "reason": "too_long",
    "conversation_id": null
  }
}

{
  "error": "RATE_LIMITED",
  "message": "Too many questions. Try again later.",
  "details": {
    "reason": "per_minute",
    "retry_after_seconds": 17,
    "remaining_today": 183
  }
}

{
  "error": "QUOTA_EXCEEDED",
  "message": "Today's Ask budget for this event is used up. Try again later.",
  "details": {
    "reason": "busy"
  }
}

{
  "status": 429,
  "success": false,
  "message": "Error while trying to reach the endpoint: Too many requests",
  "name": "TooManyRequestsError"
}

{
  "error": "INTERNAL_ERROR",
  "message": "Ask could not answer right now."
}