---
title: "Retrieval over the public talk archive"
method: POST
path: "/api/presentations/ask"
tags: ["research"]
---

# Retrieval over the public talk archive

`POST /api/presentations/ask`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/presentations/ask`
- Auth: none required

PUBLIC and retrieval-only, unlike POST /api/research/ask which is member-gated. Returns matching talk slides with deep links; there is deliberately NO model synthesis here, because that is the costly and abusable part. Bounded by a per-IP hourly budget that fails CLOSED, so a caller who can stall the counter cannot flood the corpus service.

## Request body

- PresentationsAskRequest
  - `q` string, required: At most 500 characters.
  - `k` integer: How many slides to return. 3-25, default 10.

## Response `200`

Matching slides with deep links.

- PresentationsAskResponse
  - `ok` boolean, required
  - `q` string, required
  - `count` integer, required
  - `results` object[], required: Retrieval only — there is deliberately no model synthesis on this surface.
    - `paper_id` string
    - `slug` string
    - `talk_title` string
    - `series` string
    - `speaker` string
    - `similarity` number
    - `slide` integer, nullable
    - `snippet` string
    - `deep_link` string: Deck URL with a #slide anchor when the chunk carries a slide number.
    - `detail_link` string
  - `via` string

## Other responses

- `400`: Missing `q`, or over the 500-character ceiling.
- `429`: Hourly IP budget exhausted.
- `502`: The retrieval service failed.
- `503`: Retrieval is not configured.
- `504`: The retrieval service timed out.

---

[API](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api.md) · [All operations](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/revisions/be67c1f67c27?raw)