Ask questions

This guide shows you how to create a session, ask a question, and verify the answer with its citations.

Use a conversation when your application needs an answer rather than a list of matching moments. A session binds one or more indexed videos to a short, server-held conversation history. Each completed answer includes citations that the user can inspect.

Before you start

• Each video must be indexed, searchable, and visible to the API key creator.
• The API key needs the QUERY_CONTENT permission.
• Set BASE_URL and DEEPFRAME_API_KEY as shown in Authentication and access.

1. Create a session

Create the session once with every video that the conversation may use:

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/sessions" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: session-create-01" \
  -d '{"video_ids":["vid_01JABC123"]}'

Save the returned opaque sess_... value:

export SESSION_ID="sess_01JSESSION123"

The returned expires_at value is the current expiry time. Reading the session, submitting a question, or polling a question refreshes session activity.

2. Submit a question

curl --fail-with-body -X POST \
  "$BASE_URL/api/v1alpha1/sessions/$SESSION_ID/queries" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: question-create-01" \
  -d '{"query":"What changed after the north door opened?"}'

The API returns HTTP 202 with an opaque qry_... identifier and a processing status. Save the identifier for polling:

export QUERY_ID="qry_01JQUERY123"

3. Poll for the answer

Poll about once per second:

curl --fail-with-body \
  "$BASE_URL/api/v1alpha1/sessions/$SESSION_ID/queries/$QUERY_ID" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY"

Stop when status is completed or failed. Both are terminal. A completed query contains the saved answer and citations. A failed query includes a reason such as query_age_exceeded or engine_error; decide whether a new question is appropriate instead of polling forever.

4. Verify the citations

Treat the answer and its citations as one result. Let the user open the cited evidence and confirm the relevant time in the source video before acting on the claim. Do not present uncited prose as verified evidence.

Ask a follow-up question

Submit another query under the same SESSION_ID. DeepFrame uses recent questions and completed answers as context, so the request contains only the new question. Do not send conversation history yourself.

Use a new idempotency key for a changed question. To review prior questions, call GET /api/v1alpha1/sessions/{session_id}/queries. For the exact request and response schemas, open the API reference.