Skip to main content
POST
/
v1
/
context
Context
curl --request POST \
  --url https://api.userepo.com/v1/context \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "limit": 123
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.userepo.com/llms.txt

Use this file to discover all available pages before exploring further.

The recommended retrieval endpoint for agents. Returns the same hits as /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:
​
query
string
required
The user-facing question or search phrase.
​
limit
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, exclusionCount
  • providers (which providers contributed hits)
The full hit content is not logged — only counts and identifiers — so the audit log stays small and compliance-safe.

​
When to use this vs /v1/search

Use /v1/context whenUse /v1/search when
Building a production agent that needs to cite sourcesPrototyping or one-off scripts
You want to know what was excluded and whyYou only care about the top hits
You’re feeding the response into an LLM promptYou’re feeding the response into your own UI
Compliance or audit requirements matterInternal-only, dev use