Recall memory
curl --request POST \
--url https://api.getmetacognition.com/recall \
--header 'Content-Type: application/json' \
--data '
{
"scope.org_id": "<string>",
"scope.session_id": "<string>",
"q": "<string>",
"mode": {},
"top_k": 123,
"include_timeline": true
}
'import requests
url = "https://api.getmetacognition.com/recall"
payload = {
"scope.org_id": "<string>",
"scope.session_id": "<string>",
"q": "<string>",
"mode": {},
"top_k": 123,
"include_timeline": True
}
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({
'scope.org_id': '<string>',
'scope.session_id': '<string>',
q: '<string>',
mode: {},
top_k: 123,
include_timeline: true
})
};
fetch('https://api.getmetacognition.com/recall', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.getmetacognition.com/recall",
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([
'scope.org_id' => '<string>',
'scope.session_id' => '<string>',
'q' => '<string>',
'mode' => [
],
'top_k' => 123,
'include_timeline' => true
]),
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 := "https://api.getmetacognition.com/recall"
payload := strings.NewReader("{\n \"scope.org_id\": \"<string>\",\n \"scope.session_id\": \"<string>\",\n \"q\": \"<string>\",\n \"mode\": {},\n \"top_k\": 123,\n \"include_timeline\": true\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("https://api.getmetacognition.com/recall")
.header("Content-Type", "application/json")
.body("{\n \"scope.org_id\": \"<string>\",\n \"scope.session_id\": \"<string>\",\n \"q\": \"<string>\",\n \"mode\": {},\n \"top_k\": 123,\n \"include_timeline\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.getmetacognition.com/recall")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"scope.org_id\": \"<string>\",\n \"scope.session_id\": \"<string>\",\n \"q\": \"<string>\",\n \"mode\": {},\n \"top_k\": 123,\n \"include_timeline\": true\n}"
response = http.request(request)
puts response.read_body{
"hits.turns": [
{}
],
"hits.observations": [
{}
],
"hits.entities": [
{}
],
"confidence": 123,
"timeline": {},
"mode": "<string>",
"usage": {}
}Memory
Recall memory
Search memory with a natural-language query and get ranked hits, confidence, and usage.
POST
/
recall
Recall memory
curl --request POST \
--url https://api.getmetacognition.com/recall \
--header 'Content-Type: application/json' \
--data '
{
"scope.org_id": "<string>",
"scope.session_id": "<string>",
"q": "<string>",
"mode": {},
"top_k": 123,
"include_timeline": true
}
'import requests
url = "https://api.getmetacognition.com/recall"
payload = {
"scope.org_id": "<string>",
"scope.session_id": "<string>",
"q": "<string>",
"mode": {},
"top_k": 123,
"include_timeline": True
}
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({
'scope.org_id': '<string>',
'scope.session_id': '<string>',
q: '<string>',
mode: {},
top_k: 123,
include_timeline: true
})
};
fetch('https://api.getmetacognition.com/recall', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.getmetacognition.com/recall",
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([
'scope.org_id' => '<string>',
'scope.session_id' => '<string>',
'q' => '<string>',
'mode' => [
],
'top_k' => 123,
'include_timeline' => true
]),
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 := "https://api.getmetacognition.com/recall"
payload := strings.NewReader("{\n \"scope.org_id\": \"<string>\",\n \"scope.session_id\": \"<string>\",\n \"q\": \"<string>\",\n \"mode\": {},\n \"top_k\": 123,\n \"include_timeline\": true\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("https://api.getmetacognition.com/recall")
.header("Content-Type", "application/json")
.body("{\n \"scope.org_id\": \"<string>\",\n \"scope.session_id\": \"<string>\",\n \"q\": \"<string>\",\n \"mode\": {},\n \"top_k\": 123,\n \"include_timeline\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.getmetacognition.com/recall")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"scope.org_id\": \"<string>\",\n \"scope.session_id\": \"<string>\",\n \"q\": \"<string>\",\n \"mode\": {},\n \"top_k\": 123,\n \"include_timeline\": true\n}"
response = http.request(request)
puts response.read_body{
"hits.turns": [
{}
],
"hits.observations": [
{}
],
"hits.entities": [
{}
],
"confidence": 123,
"timeline": {},
"mode": "<string>",
"usage": {}
}This is the REST version of
Response —
tex.recall. Use it before generation to get the memory your model should read. For mode, top_k, and confidence, see Recall and ranking.
Headers
Authorization: Bearer <access_token>
Content-Type: application/json
Body
{
"scope": {
"org_id": "org_...",
"session_id": "chat-1"
},
"q": "what does the user prefer?",
"mode": "active",
"top_k": 5,
"include_timeline": false
}
string
required
Your org id. Minimum length is 1 character. The server still uses the JWT’s
org_id claim for tenancy; this field is required for request validation.string
Session to search. Optional. Falls back to the JWT’s
session_id.string
required
Natural-language query.
min_length=1."active" | "deep"
default:"\"active\""
Retrieval depth. See Recall and ranking.
integer
Hits to return across all kinds. Defaults to 15 (active) / 25 (deep). Request validation accepts
1 <= top_k <= 50; runtime caps the final value at 30.boolean
default:"false"
Attach a chronological summary string to the response.
Response — 200
array
Ranked raw turns.
array
Atomic facts.
array
Linked entities. Each entity has
{id?, label, score}. This is different from turns and observations.number
Calibrated [0, 1].
string | null
Pre-rendered chronological summary, set only when
include_timeline=true.string
Echoes request mode.
object
{tokens_in, tokens_out} for this call.Hit fields
{
"id": "c9fcfbf51b03bbc3...",
"text": "[user] I'm allergic to shellfish.",
"score": 0.42,
"kind": "turn",
"timestamp": "1778061473326"
}
Example
curl -X POST https://api.getmetacognition.com/recall \
-H "Authorization: Bearer $JWT" \
-H 'content-type: application/json' \
-d '{
"scope": {"org_id":"org_…","session_id":"chat-1"},
"q": "any food restrictions?",
"top_k": 3
}'
import httpx
resp = httpx.post(
"https://api.getmetacognition.com/recall",
headers={"Authorization": f"Bearer {jwt}"},
json={
"scope": {"org_id": "org_…", "session_id": "chat-1"},
"q": "any food restrictions?",
"top_k": 3,
},
timeout=10,
)
hits = resp.json()
for t in hits["hits"]["turns"]:
print(f"[{t['score']:.2f}] {t['text']}")
Response
{
"hits": {
"observations": [],
"turns": [
{
"id": "c9fcfbf5...",
"text": "[Date: 2026-05-08T14:00:00Z] [user] I'm allergic to shellfish",
"score": 0.4268,
"kind": "turn",
"timestamp": "1778061473326"
}
],
"entities": []
},
"timeline": null,
"confidence": 0.067,
"mode": "active",
"usage": { "tokens_in": 6, "tokens_out": 27 }
}

