Skip to main content
POST
Ask Question
Ask a question to your AI-powered Q&A assistant and receive a detailed response with references.
To ask follow-up questions, include the session_id from a previous response in your request. This allows the Guru to maintain context of the conversation.

Path Parameters

string
required
The slug of the Guru to ask a question to

Headers

string
required
Your API key for authentication. You can obtain your API key from the Gurubase dashboard.

Body Parameters

string
required
The question to ask your Guru
boolean
default:false
Whether to stream the response or not. If true, only the content of the response will be returned in chunks.
string
default:"chat"
Selects the answer pipeline for this request. Accepted values:
  • chat (default): the classic single-pass answer pipeline.
  • agent: the autonomous tool loop, which lets the Guru chain Agentic Actions and other tools before answering.
agent requires an agent-capable Guru (multi-step answers enabled with at least one usable tool). If the Guru does not qualify, the request silently falls back to chat. Any unrecognized value is also treated as chat.
string
Maintain conversation context for follow-up questions. When a question is asked, the response includes a session_id that can be used in subsequent requests. On the Gurubase platform, these conversation sessions are called “Binges”.
string
External user identifier for tracking user-specific conversation sessions. When provided, this ID is stored in the session. If a session already exists with a different external_user_id, the request will be rejected.
object
Optional free-form caller labels attached to the question. The object is stored with the question; it is never injected into the prompt on its own.Limits:
  • Flat object only (no nested objects or arrays); at most 10 keys.
  • Keys are strings up to 64 characters and must match [A-Za-z0-9_.-]+.
  • Keys starting with gurubase_ are reserved and rejected.
  • Values must be a string, number, or boolean. String values are limited to 256 characters.
  • null values are accepted and dropped from the stored object before persistence (the key is not stored).
  • Any other violation returns HTTP 400 before any answer is generated.
Gurubase can configure a Guru to map a specific metadata key onto a subject inside the stored user profile (contact support to enable it). For example, an accountId key can select one account from a profile that covers several, pushed via Upsert Profiles. When such a mapping is configured on the Guru, sending that key on the request pins the answer to that subject: only that subject’s profile detail is used, memories about other subjects are held back, and identical wording asked about a different subject gets its own answer.Subject pinning requires the request to also include the same external_user_id used when the profile was pushed via Upsert Profiles; that identifier is how the profile is looked up. Without it no profile is loaded and the mapped metadata key does not pin the answer. Omit the mapped key to answer against the whole profile. An unknown subject id degrades to an unpinned answer rather than failing the request.
boolean
default:false
Fetch an existing answer. Do not ask a new question (generally used after streaming to fetch the answer fields like references etc.).
number[]
Optional list of data source IDs to scope the answer to. When provided, retrieval only reads from these sources, so a question like “what did we decide in Monday’s standup” can be pinned to a single transcript instead of the full knowledge base. IDs are the numeric identifiers returned by Create / Get Data Sources and must belong to the same Guru.
string[]
Optional list of data source labels to scope the answer to. Only sources tagged with at least one of the given labels are considered during retrieval.
boolean
default:true
Whether the Guru’s End-User Memory is read from or written to for this request. Set to false when a bot or integration is asking on behalf of a user whose profile should not be built up (for example, a meeting assistant asking on a participant’s behalf). Disables both reading and writing for the single request.
array
Optional list of image attachments to include with the question. Each item is an object with:
  • data (string): Base64-encoded image as a data URL, formatted as data:<mime>;base64,<payload> (see the encode_binary helper in the “Asking With Attachments” example).
  • name (string): File name (e.g. screenshot.png).
  • type (string): MIME type (e.g. image/png).
Item count and per-file size are subject to the Guru’s limits. Images exceeding the limits are silently skipped and the response includes a note with how many were dropped.
array
Optional list of log file attachments to include with the question. Each item is an object with:
  • data (string): Raw UTF-8 log text (see the read_log helper in the “Asking With Attachments” example). Not base64-encoded.
  • name (string): File name (e.g. app.log).
Item count and per-file size are subject to the Guru’s limits. Log files exceeding the limits are silently skipped and the response includes a note with how many were dropped.
array
Optional list of PDF attachments to include with the question. Each item is an object with:
  • data (string): Base64-encoded PDF as a data URL, formatted as data:<mime>;base64,<payload> (see the encode_binary helper in the “Asking With Attachments” example).
  • name (string): File name (e.g. doc.pdf).
  • type (string): MIME type (typically application/pdf).
Item count and per-file size are subject to the Guru’s limits. Unlike images and log files, PDFs are validated upfront: if the request exceeds the limits, the endpoint returns HTTP 400 and no answer is generated.

Response

string
Unique identifier for the question-answer pair
string
The answer in Markdown format
string
The original question
string
The date when the answer was generated
number
Confidence score of the answer (0-100)
array
Array of reference sources used to generate the answer
string
Unique identifier for the conversation session
string
URL link to open the question on the app
boolean
Whether the question can receive votes and feedback. Returns false for simple interactions and clarifications, true for normal answers. See the Record Vote endpoint for more information on providing feedbacks and votes.
When stream=true, the response will be a text stream containing only the answer content in chunks, not the full JSON object. The JSON response format shown below applies only when stream=false (default).
When the Guru refuses a question, the error response carries a stable code field so callers can branch without matching on the wording of msg. QUESTION_NOT_RELATED means the question falls outside the Guru’s topic; NOT_ENOUGH_DATA means the knowledge base did not contain enough context to answer confidently. Branch on code, not on msg: a Guru can set its own refusal messages, and msg then carries that text.

Code Examples

Stream a response for real-time output, then fetch the completed answer to get metadata like trust_score, references, and session_id.