> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useparagon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Context API

> Search your users' synced content and read the text around a search result.

The Context API lets your agent find relevant content from your users' connected knowledge sources, then read more of the surrounding text when a result looks promising. Requests are sent to the [Agent OS base URL](https://docs.useparagon.com/agent-os/overview.md#base-url) and are authenticated with a Paragon User Token.

## How it works

**1. Create a Setup Link**

Your backend calls [Create Setup Link](https://docs.useparagon.com/agent-os/context/create-setup-link.md) for a Connected User and gets back a hosted URL. Send that URL to your user.

**2. Your user connects their apps**

The Setup Link opens a hosted page where your user connects the apps they want your agent to search, such as Google Drive, Box, or SharePoint. Apps they've already connected show a green check.

![The Setup Link app catalog, showing connected apps and available integrations grouped by category](https://mintcdn.com/paragon/hdX-Dot0wWXPQySZ/assets/context-setup-link-connect-apps.png?fit=max\&auto=format\&n=hdX-Dot0wWXPQySZ\&q=85\&s=e073abacc13e1992051bc2aef554b06f)

**3. Your user chooses what to sync**

After connecting an app, your user picks the folders and files to include in their searchable content. The page shows how much content has been discovered and is searchable, and the sync status of each selection.

![The Manage synced content page, showing discovery progress and a list of folders with checkboxes and sync status](https://mintcdn.com/paragon/hdX-Dot0wWXPQySZ/assets/context-setup-link-manage-content.png?fit=max\&auto=format\&n=hdX-Dot0wWXPQySZ\&q=85\&s=d5126dd9982a7e090e90d5f303de195d)

**4. Search the content**

Once content is synced and indexed, your agent finds relevant passages with [Search Context](https://docs.useparagon.com/agent-os/context/search.md) and reads more of the surrounding text with [Read Segment Context](https://docs.useparagon.com/agent-os/context/read-segment.md).

```mermaid theme={null}
flowchart LR
  subgraph customer["Your Customer"]
    direction LR
    setup["Views<br/>Setup Link"] --> connect["Connects<br/>sources"]
  end

  sources["Knowledge Sources, e.g. Google Drive"]

  subgraph paragon["Paragon"]
    direction LR
    sync["Creates<br/>syncs"] --> indexContent["Indexes<br/>content"]
    indexContent --> contextApi["Context API"]
  end

  subgraph yourApp["Your App"]
    search["Searches<br/>content"]
  end

  connect --> sources
  sources <--> sync
  search --> contextApi

  classDef customerNode fill:#EAF4FF,stroke:#2F80ED,color:#1F2937;
  classDef sourceNode fill:#FFF4E5,stroke:#B7791F,color:#1F2937;
  classDef paragonNode fill:#F3ECFF,stroke:#6B46C1,color:#1F2937;
  classDef appNode fill:#EAFBF1,stroke:#27AE60,color:#1F2937;

  class setup,connect customerNode;
  class sources sourceNode;
  class sync,indexContent,contextApi paragonNode;
  class search appNode;

  style customer fill:#F7FBFF,stroke:#9CCBFF,color:#1F2937;
  style paragon fill:#FBF8FF,stroke:#C4B5FD,color:#1F2937;
  style yourApp fill:#F6FEF9,stroke:#9AE6B4,color:#1F2937;
```

## Endpoints

| Endpoint | Use it to |
| - | - |
| [Create Setup Link](https://docs.useparagon.com/agent-os/context/create-setup-link.md) | Create a hosted link where a user connects the sources to sync. |
| [Search Context](https://docs.useparagon.com/agent-os/context/search.md) | Find the passages that best match a query. |
| [Read Segment Context](https://docs.useparagon.com/agent-os/context/read-segment.md) | Read the text before and after a passage returned by search. |

## How search results are organized

Search returns one result per record. A record is one item (for example, a file or page) in one sync. If the same item is included in two syncs, it appears as two results.

Each result includes its best matching passages. Every passage has a `pointer` that you can pass to [Read Segment Context](https://docs.useparagon.com/agent-os/context/read-segment.md) to retrieve more of the surrounding text.

## Supported sources

You can limit a search to specific sources with the `sources` field:

`onedrive`, `sharepoint`, `dropbox`, `box`, `confluence`, `googledrive`

## Respecting user permissions

Search results only include content the user is allowed to access in the source app. Use `identity` to tell Agent OS which account to apply on each source.

| Field | Where | Description |
| - | - | - |
| `identity` | Request body on search. Query parameter on segment read. | The account whose access applies. Pass a string to use one account on every source. On search, you can instead pass an array of 1 to 20 `{ principal, source }` entries to use a different account for each source. The segment read endpoint only accepts the string form. |
| `email` | Request body or query parameter | Deprecated. Use `identity` instead. |

The `principal` can be an email address or a provider-specific user ID. When you use a provider-specific ID rather than an email, you must also set `source`.

```json theme={null}
{
  "query": "q2 roadmap",
  "identity": [
    { "principal": "user@example.com", "source": "googledrive" },
    { "principal": "00uabc", "source": "sharepoint" }
  ]
}
```