Skip to main content
/v1/context returns a Context Contract — a richer envelope than /v1/search that documents not just what was retrieved but also what was excluded and why. It’s designed for agents that need to reason about their own context window honestly.

​
Why a contract instead of just hits

A bare hit list looks the same whether retrieval found everything relevant or got blocked by a scope. An honest agent needs to know the difference. The contract makes it explicit:
  • What did you ask for?
  • What did Repo retrieve?
  • What did Repo exclude, and why?
  • What are the freshness + access caveats?

​
Shape

{
  "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": [
    {
      "sourceItemId": "uuid",
      "title": "Brand decisions",
      "content": "We're keeping the lime-green accent...",
      "url": "https://www.notion.so/...",
      "provider": "notion",
      "score": 0.8432,
      "freshness": { "syncedAt": "2026-05-30T20:00:00Z", "ageHours": 0.2 },
      "accessPolicy": { "provider": "notion", "mode": "provider_scope", "workspaceId": "..." }
    }
  ],
  "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."
    },
    {
      "type": "no_results",
      "provider": "slack",
      "reason": "The provider was allowed for this key, but no matching context was returned."
    }
  ],
  "limitations": [
    {
      "code": "provider_scope_applied",
      "message": "Only notion, slack memory was eligible for retrieval."
    }
  ]
}

​
Field reference

​
contract

FieldMeaning
versionSchema version. Current: "1.0".
requestIdUUID for this exact retrieval — match it against audit events.
endpointWhich Repo endpoint produced the contract.
issuedAtUTC timestamp the contract was generated.
callerActorTypeagent / application / admin — from the key’s metadata.
callerApiKeyIdThe API key that authenticated the call.

​
hits

Array of retrieved source items, ordered by score descending.
FieldMeaning
sourceItemIdStable Repo ID. Use this for follow-up /v1/source-items/:id calls (coming soon).
titleSource-provided title (Slack message text, Notion page title, Drive filename).
contentThe chunk text that matched.
urlDeep-link back to the original source.
providerslack / notion / google_drive / gmail.
scoreCosine similarity to the query embedding, 0.0 — 1.0.
freshness.syncedAtWhen this source was last synced by Repo.
freshness.ageHoursHow stale the data is, rounded to 0.1h.
accessPolicyPer-provider access metadata preserved at ingest.

​
citations

A numbered citation list ready to inject into your LLM prompt. Each citation references a sourceItemId so your agent can resolve [1] → “Brand decisions” → the actual Notion URL.

​
exclusions

The most important field for honest agents. Each entry explains a piece of context the agent did not receive.
typeMeaning
provider_scopeThe key’s allowedProviders excluded this provider entirely.
no_resultsThe provider was allowed but the vector search returned nothing relevant.

​
limitations

Higher-level caveats about the retrieval, e.g.:
  • no_context — Repo found nothing matching this query within the caller’s scope.
  • provider_scope_applied — Note that scope filtering was active.
  • missing_sync_timestamp — One or more sources lack freshness metadata.
  • missing_source_access_policy — One or more sources don’t yet have preserved ACL data (Drive specifically).

​
Why this shape

Repo treats the agent as a participant in a structured exchange, not a black-box consumer of search hits. The contract makes it possible to:
  • Cite sources precisely in answers ([1] → real URL)
  • Tell the user “I have additional context I’m not allowed to share” instead of hallucinating
  • Surface freshness so the agent can hedge (“This is from 6 hours ago — let me check the latest”)
  • Audit retrieval after the fact via requestId

​
Use the simpler endpoint if you don’t need this

/v1/search returns just the hits array — same retrieval, no envelope. Use it when you’re prototyping or your agent doesn’t care about exclusions.