Context
curl --request POST \
--url https://api.userepo.com/v1/context \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"limit": 123
}
'import requests
url = "https://api.userepo.com/v1/context"
payload = {
"query": "<string>",
"limit": 123
}
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: '<string>', limit: 123})
};
fetch('https://api.userepo.com/v1/context', 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.userepo.com/v1/context",
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' => '<string>',
'limit' => 123
]),
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.userepo.com/v1/context"
payload := strings.NewReader("{\n \"query\": \"<string>\",\n \"limit\": 123\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.userepo.com/v1/context")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"<string>\",\n \"limit\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.userepo.com/v1/context")
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 \"query\": \"<string>\",\n \"limit\": 123\n}"
response = http.request(request)
puts response.read_bodyReference
Context
Search with a structured Context Contract — hits, citations, exclusions, and limitations.
POST
/
v1
/
context
Context
curl --request POST \
--url https://api.userepo.com/v1/context \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"limit": 123
}
'import requests
url = "https://api.userepo.com/v1/context"
payload = {
"query": "<string>",
"limit": 123
}
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: '<string>', limit: 123})
};
fetch('https://api.userepo.com/v1/context', 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.userepo.com/v1/context",
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' => '<string>',
'limit' => 123
]),
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.userepo.com/v1/context"
payload := strings.NewReader("{\n \"query\": \"<string>\",\n \"limit\": 123\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.userepo.com/v1/context")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"<string>\",\n \"limit\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.userepo.com/v1/context")
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 \"query\": \"<string>\",\n \"limit\": 123\n}"
response = http.request(request)
puts response.read_bodyThe recommended retrieval endpoint for agents. Returns the same hits as
When to use this vs
/v1/search but wraps them in a Context Contract so your agent knows exactly what was retrieved and what was excluded.
Required action
context
Cost
1 credit per call. Same billing rules as/v1/search and /v1/ask.
Body
Same as/v1/search:
string
required
The user-facing question or search phrase.
integer
default:"8"
Maximum number of hits. Min 1, max 25.
Response
Full Context Contract — see the Context Contract concept page for the complete field reference. Abbreviated:{
"contract": {
"version": "1.0",
"requestId": "uuid",
"endpoint": "/v1/context",
"issuedAt": "2026-05-30T20:14:00Z",
"callerActorType": "agent",
"callerApiKeyId": "uuid"
},
"query": { "raw": "What did we decide about the brand color?", "limit": 8 },
"hits": [ /* same shape as /v1/search */ ],
"citations": [
{ "index": 1, "sourceItemId": "uuid", "title": "Brand decisions" }
],
"exclusions": [
{
"type": "provider_scope",
"provider": "gmail",
"reason": "The authenticating API key is not allowed to retrieve this provider."
}
],
"limitations": [
{
"code": "provider_scope_applied",
"message": "Only notion, slack memory was eligible for retrieval."
}
]
}
Audit logging
Every/v1/context call records a context.retrieve audit event with metadata-only fields:
requestId(matches the contract)query(the search phrase)hitCount,citationCount,exclusionCountproviders(which providers contributed hits)
When to use this vs /v1/search
Use /v1/context when | Use /v1/search when |
|---|---|
| Building a production agent that needs to cite sources | Prototyping or one-off scripts |
| You want to know what was excluded and why | You only care about the top hits |
| You’re feeding the response into an LLM prompt | You’re feeding the response into your own UI |
| Compliance or audit requirements matter | Internal-only, dev use |