> ## 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.

# Context

> Search with a structured Context Contract — hits, citations, exclusions, and limitations.

The recommended retrieval endpoint for agents. Returns the same hits as [`/v1/search`](/api-reference/search) but wraps them in a [Context Contract](/concepts/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`:

<ParamField body="query" type="string" required>
  The user-facing question or search phrase.
</ParamField>

<ParamField body="limit" type="integer" default="8">
  Maximum number of hits. Min 1, max 25.
</ParamField>

## Response

Full Context Contract — see the [Context Contract concept page](/concepts/context-contract) for the complete field reference. Abbreviated:

```json theme={null}
{
  "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` 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                       |