Context Contract

/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`

Field	Meaning
`version`	Schema version. Current: `"1.0"`.
`requestId`	UUID for this exact retrieval — match it against audit events.
`endpoint`	Which Repo endpoint produced the contract.
`issuedAt`	UTC timestamp the contract was generated.
`callerActorType`	`agent` / `application` / `admin` — from the key’s metadata.
`callerApiKeyId`	The API key that authenticated the call.

`hits`

Array of retrieved source items, ordered by score descending.

Field	Meaning
`sourceItemId`	Stable Repo ID. Use this for follow-up `/v1/source-items/:id` calls (coming soon).
`title`	Source-provided title (Slack message text, Notion page title, Drive filename).
`content`	The chunk text that matched.
`url`	Deep-link back to the original source.
`provider`	`slack` / `notion` / `google_drive` / `gmail`.
`score`	Cosine similarity to the query embedding, 0.0 — 1.0.
`freshness.syncedAt`	When this source was last synced by Repo.
`freshness.ageHours`	How stale the data is, rounded to 0.1h.
`accessPolicy`	Per-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.

`type`	Meaning
`provider_scope`	The key’s `allowedProviders` excluded this provider entirely.
`no_results`	The 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.

Get started

Core concepts

Connectors

Operations

Context Contract

Why a contract instead of just hits

Shape

Field reference

`contract`

`hits`

`citations`

`exclusions`

`limitations`

Why this shape

Use the simpler endpoint if you don’t need this

​Why a contract instead of just hits

​Shape

​Field reference

​contract

​hits

​citations

​exclusions

​limitations

​Why this shape

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

Why a contract instead of just hits

Shape

Field reference

`contract`

`hits`

`citations`

`exclusions`

`limitations`

Why this shape

Use the simpler endpoint if you don’t need this