> ## Documentation Index > Fetch the complete documentation index at: https://apidocs.sessionboard.com/llms.txt > Use this file to discover all available pages before exploring further. # Ask a question about an event > 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. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/event/{eventId}/ask openapi: 3.1.0 info: title: Sessionboard Public API version: '1.0' description: >- REST API for managing sessions, speakers, contacts, sponsors, exhibitors, and event data on the Sessionboard platform. contact: name: Sessionboard Support email: support@sessionboard.com termsOfService: https://www.sessionboard.com/legal/terms-of-service servers: - url: https://public-api.sessionboard.com description: US Region - url: https://public-api-eu.sessionboard.com description: EU Region security: - ApiKey: [] - BearerToken: [] tags: - name: Events description: Manage events on the platform. - name: Sessions description: Search and retrieve sessions within an event. - name: Session Writes description: >- Create, update, delete, and restore sessions. Requires the `write:sessions` scope. - name: Contact Writes description: >- Create, update, delete, and restore contacts. Requires the `write:contacts` scope. - name: Exhibitor Writes description: >- Create, update, delete, and restore exhibitors. Requires the `write:exhibitors` scope. - name: Sponsor Writes description: >- Create, update, delete, and restore sponsors. Requires the `write:sponsors` scope. - name: Field Writes description: >- Create, update, and delete custom fields. Requires the `write:fields` scope. - name: Speakers description: Search and retrieve speakers within an event. - name: Participants description: | Search and retrieve every contact holding a session role on an event — speakers, chairpersons, moderators and custom roles — with the roles each one holds, and list the event's participant roles. - name: Contacts description: Search and retrieve contacts at the organization or event level. - name: Sponsors description: Search and retrieve sponsors within an event. - name: Exhibitors description: Search and retrieve exhibitors within an event. - name: Event Settings description: >- Retrieve event configuration such as fields, tags, tracks, rooms, formats, levels, languages, and session statuses. - name: GDPR description: Manage GDPR data access and erasure requests. - name: Insights description: >- Query event data using SbQL, generate queries with AI, and manage dashboards. - name: Ask description: >- Ask a natural-language question about one event and get a cited answer. Requires the `read:ask` scope, granted explicitly. - name: Metadata Writes description: >- Create, update, and delete session metadata (rooms, tracks, tags, formats, levels, languages, statuses). Requires the `write:metadata` scope. - name: Agenda Planning description: >- Manage agenda drafts, draft sessions, scheduling rules, and evaluation personas. Requires the `write:events` scope. - name: Dashboards & Widgets description: >- Create, read, update, and delete dashboards and widgets at the event or organization level. Requires `write:events` scope for writes. - name: Reports & Queries description: >- Create, read, update, delete, and run saved SbQL queries/reports at the event or organization level. Requires `write:events` scope for writes. - name: Transcriptions description: >- Transcript text on sessions — fragments, summaries, insights, and translations. Requires `read:transcriptions` / `write:transcriptions` scopes. - name: Session Recordings description: >- Session audio files for recording archives (live capture or imported audio). Requires `read:transcriptions` / `write:transcriptions` scopes. - name: Media description: >- Upload video or audio files for automatic transcription. Requires `read:media` / `write:media` scopes. - name: Session Files description: > Documents attached to sessions (PDFs, PowerPoint, Word, images, and similar). Simple upload: `POST .../files/upload` (multipart, max 50 MB). Direct-to-storage: create → PUT → complete (max 500 MB). Requires `read:sessions` / `write:sessions` scopes. See the [Uploading session files](/guides/uploading-session-files) guide. - name: OAuth description: >- OAuth 2.1 endpoints for AI client authorization (Claude, ChatGPT). Mounted at `/oauth/` (not `/v1/`). - name: Log Export description: > Pull your organization's API request, security and audit logs into a SIEM such as Splunk, Microsoft Sentinel or Elastic. Requires a dedicated API token with the `read:audit_logs` scope, which can call nothing else. See the [Exporting logs to a SIEM](/guides/exporting-logs-to-a-siem) guide. - name: Awards description: >- Read and manage Awards programs and their categories, rounds, promo codes, submissions and reviews. Organization-level: paths start at `/v1/organization/{orgId}/awards`. Requires `read:awards` / `write:awards` scopes. paths: /v1/event/{eventId}/ask: post: tags: - Ask summary: Ask a question about an event description: > 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. operationId: ask-event parameters: - name: eventId in: path required: true schema: type: integer description: The event to ask about. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AskRequest' example: question: Which sessions on Tuesday cover AI? lang: en responses: '200': description: The answer and its sources. headers: RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' content: application/json: schema: $ref: '#/components/schemas/AskResponse' example: 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 '400': description: > 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': description: Missing, invalid, revoked or expired token. '403': description: > - `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`). content: application/json: schema: $ref: '#/components/schemas/AskError' examples: scope_required: summary: Token lacks read:ask value: error: SCOPE_REQUIRED message: This operation requires the 'read:ask' scope. event_not_allowed: summary: Event outside the token's allow-list value: error: EVENT_NOT_ALLOWED message: This API token is not allowed to access this event ai_disabled: summary: Organization AI features off value: error: AI_DISABLED message: AI features are not enabled for this organization ask_off: summary: Ask switched off for the event value: error: FORBIDDEN message: Ask is switched off for this event. details: reason: 'off' out_of_credits: summary: Organization out of AI credits value: error: FORBIDDEN message: Out of AI credits. Add credits to continue. details: reason: ai_credits '404': description: The event does not exist or belongs to another organization. '422': description: > `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). content: application/json: schema: $ref: '#/components/schemas/AskError' example: error: VALIDATION_ERROR message: Ask could not take that question. details: reason: too_long conversation_id: null '429': description: > - `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](/rate-limiting). headers: Retry-After: description: Seconds to wait before asking again. schema: type: integer content: application/json: schema: oneOf: - $ref: '#/components/schemas/AskError' - $ref: '#/components/schemas/TooManyRequestsError' examples: rate_limited: summary: Per-user question limit value: error: RATE_LIMITED message: Too many questions. Try again later. details: reason: per_minute retry_after_seconds: 17 remaining_today: 183 quota_exceeded: summary: Event's daily Ask budget used up value: error: QUOTA_EXCEEDED message: >- Today's Ask budget for this event is used up. Try again later. details: reason: busy api_rate_limit: summary: API token or organization request limit value: status: 429 success: false message: >- Error while trying to reach the endpoint: Too many requests name: TooManyRequestsError '500': description: '`INTERNAL_ERROR` — Ask could not answer right now. Retry later.' content: application/json: schema: $ref: '#/components/schemas/AskError' example: error: INTERNAL_ERROR message: Ask could not answer right now. '504': description: No answer within 90 seconds. Retry, or ask a narrower question. components: schemas: AskRequest: type: object additionalProperties: false required: - question properties: question: type: string minLength: 2 maxLength: 500 description: > 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`. conversation_id: type: string format: uuid description: >- The `conversation_id` from a previous answer, to ask a follow-up in the same thread. lang: type: string maxLength: 16 pattern: ^[A-Za-z]{2,3}([-_][A-Za-z0-9]{2,8})?$ description: Answer language as a language tag, e.g. `en`, `fr`, `pt-BR`. AskResponse: type: object required: - status - answer - citations - actions - conversation_id - message_id properties: status: type: string enum: - ok answer: type: string description: The answer as Markdown. `[n]` marks citation `n`. citations: type: array items: $ref: '#/components/schemas/AskCitation' actions: type: array maxItems: 0 items: {} description: Always empty — this endpoint is read-only. conversation_id: type: string format: uuid description: >- Send this back with a follow-up question to continue the conversation. message_id: type: string format: uuid description: The id of this answer. AskError: type: object required: - error properties: error: type: string enum: - VALIDATION_ERROR - SCOPE_REQUIRED - EVENT_NOT_ALLOWED - AI_DISABLED - FORBIDDEN - RATE_LIMITED - QUOTA_EXCEEDED - INTERNAL_ERROR message: type: string details: type: object description: >- `reason`, and for `RATE_LIMITED` also `retry_after_seconds` and `remaining_today`. properties: reason: type: string enum: - empty - too_long - blocked - repeated - per_minute - daily - busy - 'off' - ai_disabled - ai_credits retry_after_seconds: type: integer remaining_today: type: integer additionalProperties: true TooManyRequestsError: type: object description: >- Body of a `429` from the API's own request limits (per token, and per organization and user). Wait `Retry-After` seconds. required: - name - message properties: status: type: integer example: 429 success: type: boolean example: false message: type: string example: 'Error while trying to reach the endpoint: Too many requests' name: type: string enum: - TooManyRequestsError AskCitation: type: object description: > A source card built from a record. `index` matches the `[n]` marker in `answer`. The fields beyond `index`, `type` and `id` depend on `type` — for example `title` and `starts_at` on a session, `name` on a speaker, `session_id`, `session_title`, `start_ms` and `text` on a transcript excerpt. required: - index - type - id properties: index: type: integer description: The `n` in the answer's `[n]` marker. type: type: string enum: - session - speaker - exhibitor - sponsor - product - poster - room - pin - info - transcript - doc - pinned - help id: type: string description: The id of the cited record. title: type: string name: type: string starts_at: type: string format: date-time session_id: type: string session_title: type: string start_ms: type: integer description: Offset into the session recording, for a transcript excerpt. text: type: string description: The quoted passage, for a transcript excerpt. additionalProperties: true headers: RateLimitLimit: description: Requests allowed in the current window. schema: type: integer RateLimitRemaining: description: Requests left in the current window. schema: type: integer securitySchemes: ApiKey: type: apiKey in: header name: x-access-token description: >- Organization API token. Generate from Organization Settings → API Tokens. BearerToken: type: http scheme: bearer description: >- OAuth 2.1 access token. Obtained via the OAuth PKCE flow at `/oauth/token`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.