Ask Stream
curl --request POST \
--url http://localhost:8080/v1/knowledge/ask/stream \
--header 'Content-Type: application/json' \
--data '
{
"query": "What are our top blockers for Q1?",
"timezone": "America/New_York",
"metadata": {
"env": "staging"
},
"filter": {
"must": [
{
"key": "source",
"match": {
"any": [
"email",
"calendar_event"
]
}
},
{
"key": "timestamp",
"range": {
"gte": "2026-01-01",
"lte": "2026-03-31"
}
}
],
"must_not": [
{
"key": "sensitivity",
"match": {
"value": "restricted"
}
}
],
"should": [
{
"key": "connection",
"match": {
"value": "gmail:acme"
}
},
{
"key": "connection",
"match": {
"value": "slack:acme"
}
}
]
}
}
'import requests
url = "http://localhost:8080/v1/knowledge/ask/stream"
payload = {
"query": "What are our top blockers for Q1?",
"timezone": "America/New_York",
"metadata": { "env": "staging" },
"filter": {
"must": [
{
"key": "source",
"match": { "any": ["email", "calendar_event"] }
},
{
"key": "timestamp",
"range": {
"gte": "2026-01-01",
"lte": "2026-03-31"
}
}
],
"must_not": [
{
"key": "sensitivity",
"match": { "value": "restricted" }
}
],
"should": [
{
"key": "connection",
"match": { "value": "gmail:acme" }
},
{
"key": "connection",
"match": { "value": "slack:acme" }
}
]
}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'What are our top blockers for Q1?',
timezone: 'America/New_York',
metadata: {env: 'staging'},
filter: {
must: [
{key: 'source', match: {any: ['email', 'calendar_event']}},
{key: 'timestamp', range: {gte: '2026-01-01', lte: '2026-03-31'}}
],
must_not: [{key: 'sensitivity', match: {value: 'restricted'}}],
should: [
{key: 'connection', match: {value: 'gmail:acme'}},
{key: 'connection', match: {value: 'slack:acme'}}
]
}
})
};
fetch('http://localhost:8080/v1/knowledge/ask/stream', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "8080",
CURLOPT_URL => "http://localhost:8080/v1/knowledge/ask/stream",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'What are our top blockers for Q1?',
'timezone' => 'America/New_York',
'metadata' => [
'env' => 'staging'
],
'filter' => [
'must' => [
[
'key' => 'source',
'match' => [
'any' => [
'email',
'calendar_event'
]
]
],
[
'key' => 'timestamp',
'range' => [
'gte' => '2026-01-01',
'lte' => '2026-03-31'
]
]
],
'must_not' => [
[
'key' => 'sensitivity',
'match' => [
'value' => 'restricted'
]
]
],
'should' => [
[
'key' => 'connection',
'match' => [
'value' => 'gmail:acme'
]
],
[
'key' => 'connection',
'match' => [
'value' => 'slack:acme'
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://localhost:8080/v1/knowledge/ask/stream"
payload := strings.NewReader("{\n \"query\": \"What are our top blockers for Q1?\",\n \"timezone\": \"America/New_York\",\n \"metadata\": {\n \"env\": \"staging\"\n },\n \"filter\": {\n \"must\": [\n {\n \"key\": \"source\",\n \"match\": {\n \"any\": [\n \"email\",\n \"calendar_event\"\n ]\n }\n },\n {\n \"key\": \"timestamp\",\n \"range\": {\n \"gte\": \"2026-01-01\",\n \"lte\": \"2026-03-31\"\n }\n }\n ],\n \"must_not\": [\n {\n \"key\": \"sensitivity\",\n \"match\": {\n \"value\": \"restricted\"\n }\n }\n ],\n \"should\": [\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"gmail:acme\"\n }\n },\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"slack:acme\"\n }\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
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))
}HttpResponse<String> response = Unirest.post("http://localhost:8080/v1/knowledge/ask/stream")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"What are our top blockers for Q1?\",\n \"timezone\": \"America/New_York\",\n \"metadata\": {\n \"env\": \"staging\"\n },\n \"filter\": {\n \"must\": [\n {\n \"key\": \"source\",\n \"match\": {\n \"any\": [\n \"email\",\n \"calendar_event\"\n ]\n }\n },\n {\n \"key\": \"timestamp\",\n \"range\": {\n \"gte\": \"2026-01-01\",\n \"lte\": \"2026-03-31\"\n }\n }\n ],\n \"must_not\": [\n {\n \"key\": \"sensitivity\",\n \"match\": {\n \"value\": \"restricted\"\n }\n }\n ],\n \"should\": [\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"gmail:acme\"\n }\n },\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"slack:acme\"\n }\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:8080/v1/knowledge/ask/stream")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"What are our top blockers for Q1?\",\n \"timezone\": \"America/New_York\",\n \"metadata\": {\n \"env\": \"staging\"\n },\n \"filter\": {\n \"must\": [\n {\n \"key\": \"source\",\n \"match\": {\n \"any\": [\n \"email\",\n \"calendar_event\"\n ]\n }\n },\n {\n \"key\": \"timestamp\",\n \"range\": {\n \"gte\": \"2026-01-01\",\n \"lte\": \"2026-03-31\"\n }\n }\n ],\n \"must_not\": [\n {\n \"key\": \"sensitivity\",\n \"match\": {\n \"value\": \"restricted\"\n }\n }\n ],\n \"should\": [\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"gmail:acme\"\n }\n },\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"slack:acme\"\n }\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"type": "status",
"message": "<string>"
}{
"error_code": "authentication_error",
"message": "Invalid or missing credentials.",
"details": {}
}{
"error_code": "quota_exceeded",
"message": "Ask refused: this workspace has used all the asks its plan includes.",
"details": {}
}{
"error_code": "permission_denied",
"message": "You do not have permission to perform this action.",
"details": {}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"type": "<string>",
"detail": "<string>",
"endpoint": "<string>",
"tier": "<string>",
"limit": 123,
"remaining": 123,
"window_seconds": 123,
"retry_after": 123,
"title": "Too Many Requests",
"status": 429,
"error_code": "rate_limit_exceeded",
"instance": "<string>"
}{
"error_code": "internal_server_error",
"message": "An unexpected error occurred.",
"details": {}
}{
"error_code": "service_unavailable",
"message": "The service is currently experiencing issues. Please try again later.",
"details": {}
}Knowledge
Ask Stream
Ask a question and stream the answering
POST
/
v1
/
knowledge
/
ask
/
stream
Ask Stream
curl --request POST \
--url http://localhost:8080/v1/knowledge/ask/stream \
--header 'Content-Type: application/json' \
--data '
{
"query": "What are our top blockers for Q1?",
"timezone": "America/New_York",
"metadata": {
"env": "staging"
},
"filter": {
"must": [
{
"key": "source",
"match": {
"any": [
"email",
"calendar_event"
]
}
},
{
"key": "timestamp",
"range": {
"gte": "2026-01-01",
"lte": "2026-03-31"
}
}
],
"must_not": [
{
"key": "sensitivity",
"match": {
"value": "restricted"
}
}
],
"should": [
{
"key": "connection",
"match": {
"value": "gmail:acme"
}
},
{
"key": "connection",
"match": {
"value": "slack:acme"
}
}
]
}
}
'import requests
url = "http://localhost:8080/v1/knowledge/ask/stream"
payload = {
"query": "What are our top blockers for Q1?",
"timezone": "America/New_York",
"metadata": { "env": "staging" },
"filter": {
"must": [
{
"key": "source",
"match": { "any": ["email", "calendar_event"] }
},
{
"key": "timestamp",
"range": {
"gte": "2026-01-01",
"lte": "2026-03-31"
}
}
],
"must_not": [
{
"key": "sensitivity",
"match": { "value": "restricted" }
}
],
"should": [
{
"key": "connection",
"match": { "value": "gmail:acme" }
},
{
"key": "connection",
"match": { "value": "slack:acme" }
}
]
}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'What are our top blockers for Q1?',
timezone: 'America/New_York',
metadata: {env: 'staging'},
filter: {
must: [
{key: 'source', match: {any: ['email', 'calendar_event']}},
{key: 'timestamp', range: {gte: '2026-01-01', lte: '2026-03-31'}}
],
must_not: [{key: 'sensitivity', match: {value: 'restricted'}}],
should: [
{key: 'connection', match: {value: 'gmail:acme'}},
{key: 'connection', match: {value: 'slack:acme'}}
]
}
})
};
fetch('http://localhost:8080/v1/knowledge/ask/stream', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "8080",
CURLOPT_URL => "http://localhost:8080/v1/knowledge/ask/stream",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'What are our top blockers for Q1?',
'timezone' => 'America/New_York',
'metadata' => [
'env' => 'staging'
],
'filter' => [
'must' => [
[
'key' => 'source',
'match' => [
'any' => [
'email',
'calendar_event'
]
]
],
[
'key' => 'timestamp',
'range' => [
'gte' => '2026-01-01',
'lte' => '2026-03-31'
]
]
],
'must_not' => [
[
'key' => 'sensitivity',
'match' => [
'value' => 'restricted'
]
]
],
'should' => [
[
'key' => 'connection',
'match' => [
'value' => 'gmail:acme'
]
],
[
'key' => 'connection',
'match' => [
'value' => 'slack:acme'
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://localhost:8080/v1/knowledge/ask/stream"
payload := strings.NewReader("{\n \"query\": \"What are our top blockers for Q1?\",\n \"timezone\": \"America/New_York\",\n \"metadata\": {\n \"env\": \"staging\"\n },\n \"filter\": {\n \"must\": [\n {\n \"key\": \"source\",\n \"match\": {\n \"any\": [\n \"email\",\n \"calendar_event\"\n ]\n }\n },\n {\n \"key\": \"timestamp\",\n \"range\": {\n \"gte\": \"2026-01-01\",\n \"lte\": \"2026-03-31\"\n }\n }\n ],\n \"must_not\": [\n {\n \"key\": \"sensitivity\",\n \"match\": {\n \"value\": \"restricted\"\n }\n }\n ],\n \"should\": [\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"gmail:acme\"\n }\n },\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"slack:acme\"\n }\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
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))
}HttpResponse<String> response = Unirest.post("http://localhost:8080/v1/knowledge/ask/stream")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"What are our top blockers for Q1?\",\n \"timezone\": \"America/New_York\",\n \"metadata\": {\n \"env\": \"staging\"\n },\n \"filter\": {\n \"must\": [\n {\n \"key\": \"source\",\n \"match\": {\n \"any\": [\n \"email\",\n \"calendar_event\"\n ]\n }\n },\n {\n \"key\": \"timestamp\",\n \"range\": {\n \"gte\": \"2026-01-01\",\n \"lte\": \"2026-03-31\"\n }\n }\n ],\n \"must_not\": [\n {\n \"key\": \"sensitivity\",\n \"match\": {\n \"value\": \"restricted\"\n }\n }\n ],\n \"should\": [\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"gmail:acme\"\n }\n },\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"slack:acme\"\n }\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:8080/v1/knowledge/ask/stream")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"What are our top blockers for Q1?\",\n \"timezone\": \"America/New_York\",\n \"metadata\": {\n \"env\": \"staging\"\n },\n \"filter\": {\n \"must\": [\n {\n \"key\": \"source\",\n \"match\": {\n \"any\": [\n \"email\",\n \"calendar_event\"\n ]\n }\n },\n {\n \"key\": \"timestamp\",\n \"range\": {\n \"gte\": \"2026-01-01\",\n \"lte\": \"2026-03-31\"\n }\n }\n ],\n \"must_not\": [\n {\n \"key\": \"sensitivity\",\n \"match\": {\n \"value\": \"restricted\"\n }\n }\n ],\n \"should\": [\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"gmail:acme\"\n }\n },\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"slack:acme\"\n }\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"type": "status",
"message": "<string>"
}{
"error_code": "authentication_error",
"message": "Invalid or missing credentials.",
"details": {}
}{
"error_code": "quota_exceeded",
"message": "Ask refused: this workspace has used all the asks its plan includes.",
"details": {}
}{
"error_code": "permission_denied",
"message": "You do not have permission to perform this action.",
"details": {}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"type": "<string>",
"detail": "<string>",
"endpoint": "<string>",
"tier": "<string>",
"limit": 123,
"remaining": 123,
"window_seconds": 123,
"retry_after": 123,
"title": "Too Many Requests",
"status": 429,
"error_code": "rate_limit_exceeded",
"instance": "<string>"
}{
"error_code": "internal_server_error",
"message": "An unexpected error occurred.",
"details": {}
}{
"error_code": "service_unavailable",
"message": "The service is currently experiencing issues. Please try again later.",
"details": {}
}Body
application/json
Required string length:
1 - 16000Example:
"What are our top blockers for Q1?"
IANA timezone identifier (e.g. "America/New_York") for resolving relative time references like "today" or "last week". Unknown identifiers are rejected. Defaults to America/New_York when omitted.
Example:
"America/New_York"
Restrict the evidence the model can ground its answer in to rows whose metadata contains ALL the given key/value pairs. Shorthand for a filter whose must lists each pair; combines with filter when both are set. Max 20 keys; string values only.
Show child attributes
Show child attributes
Example:
{ "env": "staging" }
Boolean scope over items. Conditions test a field: source (source type such as email, slack_message, calendar_event, or a custom kind), connection (the connected account or custom connector, such as gmail:acme), timestamp (a date range), or any metadata tag you set at ingest on custom-connector items. must is AND, should is OR, must_not is NOT; nest a filter condition to group. Max depth 3. Example: emails and meetings from Q1 2026 in either of two accounts, excluding items tagged restricted. Any scope switches the answer to evidence retrieval only, so the model searches and reads matching records instead of querying your knowledge graph.
Show child attributes
Show child attributes
Example:
{
"must": [
{
"key": "source",
"match": { "any": ["email", "calendar_event"] }
},
{
"key": "timestamp",
"range": { "gte": "2026-01-01", "lte": "2026-03-31" }
}
],
"must_not": [
{
"key": "sensitivity",
"match": { "value": "restricted" }
}
],
"should": [
{
"key": "connection",
"match": { "value": "gmail:acme" }
},
{
"key": "connection",
"match": { "value": "slack:acme" }
}
]
}
Response
Server-Sent Events stream. Each SSE message is one JSON AskStreamEvent, discriminated by type; comment lines (: ping) keep the connection alive and carry no data. The stream closes after the final answer or error event and cannot be resumed — re-send the question to try again. Experimental — ignore unknown event types.
Was this page helpful?