> ## 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. # Search Context > Search your users' synced content and return the best matching passages. Search returns up to `topK` records (default 10, maximum 50). Each record includes up to `segmentsPerRecord` matching passages (default 1, maximum 5). Results are ordered by `relevancy`, a rank-based score for ordering results within a single response. Don't compare `relevancy` values across different requests. When reranking is applied, `rerankScore` holds the reranker's score for that passage. Otherwise it is `null`. To read more of the text around a passage, pass its `pointer` to [Read Segment Context](https://docs.useparagon.com/agent-os/context/read-segment.md). ```javascript theme={null} const response = await fetch( `https://agentos.useparagon.com/api/context/projects/${projectId}/search`, { method: "POST", headers: { Authorization: `Bearer ${paragonUserToken}`, "Content-Type": "application/json", }, body: JSON.stringify({ query: "q2 roadmap", topK: 10, segmentsPerRecord: 1, identity: "user@example.com", }), }, ); ``` ## OpenAPI ````yaml agent-os/openapi/context.json POST /api/context/projects/{projectId}/search openapi: 3.1.0 info: title: Agent OS Context API version: 1.0.0 description: Search your users' synced content and read the text around a search result. servers: - url: https://agentos.useparagon.com description: Production US Cloud - url: https://agentos.eu.paragon.so description: Production EU Cloud security: - bearerAuth: [] paths: /api/context/projects/{projectId}/search: post: summary: Search Context operationId: searchContext parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchRequest' example: query: q2 roadmap topK: 10 segmentsPerRecord: 1 sources: - googledrive identity: user@example.com responses: '200': description: The matching records and their best passages. content: application/json: schema: $ref: '#/components/schemas/SearchResponse' example: results: - id: 6f1c0b2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f.rec_1 syncId: 6f1c0b2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f source: googledrive relevancy: 1 rerankScore: 0.82 generation: 3 displayName: Q2 roadmap segments: - pointer: chk_anchor chunkId: chk_anchor text: The Q2 roadmap covers launch dates. relevancy: 1 rerankScore: 0.82 usage: returned: 1 segmentsReturned: 1 generation: 3 retrievalMode: hybrid rerankOutcome: applied dropped: segmentsBeyondPoolCap: 0 segmentsUnjoinable: 0 segmentsNotSearchable: 0 recordsBeyondTopK: 0 permissionFiltered: true identities: applied: googledrive: - user@example.com unused: [] '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' components: parameters: ProjectId: name: projectId in: path required: true schema: type: string format: uuid description: >- Your Paragon Project ID. Must match the Project ID in your Paragon User Token. schemas: SearchRequest: type: object required: - query additionalProperties: false properties: query: type: string minLength: 1 maxLength: 1024 description: The text to search for. sources: type: array maxItems: 6 items: $ref: '#/components/schemas/ContentSource' description: >- Limit the search to these sources. If omitted, all sources are searched. syncIds: type: array maxItems: 50 items: type: string format: uuid description: Limit the search to these syncs. If omitted, all syncs are searched. topK: type: integer minimum: 1 maximum: 50 default: 10 description: The maximum number of records to return. segmentsPerRecord: type: integer minimum: 1 maximum: 5 default: 1 description: The maximum number of matching passages to return for each record. rerank: type: boolean description: Set to false to skip reranking the results. identity: description: >- The account whose access applies. Pass a string to use one account on every source, or an array to use a different account for each source. oneOf: - type: string maxLength: 1024 - type: array minItems: 1 maxItems: 20 items: $ref: '#/components/schemas/CallerIdentityEntry' email: type: string maxLength: 1024 deprecated: true description: Deprecated. Use identity instead. SearchResponse: type: object required: - results - usage properties: results: type: array items: $ref: '#/components/schemas/SearchResult' usage: $ref: '#/components/schemas/SearchUsage' description: Details about how the search was run. ContentSource: type: string enum: - onedrive - sharepoint - dropbox - box - confluence - googledrive CallerIdentityEntry: type: object required: - principal properties: principal: type: string maxLength: 1024 description: >- The user's email address or provider-specific user ID. If you pass a provider-specific ID instead of an email, you must also set source. source: $ref: '#/components/schemas/ContentSource' description: The source this account applies to. SearchResult: type: object required: - id - syncId - source - relevancy - rerankScore - segments - generation properties: id: type: string description: Unique ID for this record, in the format {syncId}.{recordId}. syncId: type: string description: The ID of the sync this record belongs to. source: type: string description: The source this record came from, such as googledrive. relevancy: type: number description: >- Rank-based score used to order records in this response. Not comparable across requests. rerankScore: oneOf: - type: number - type: 'null' description: >- The reranker's score for this record, or null if it was not reranked. segments: type: array items: $ref: '#/components/schemas/Segment' description: The best matching passages in this record. generation: type: number description: The version of the record's index that produced this result. displayName: oneOf: - type: string - type: 'null' description: The record's name, such as a file name or page title, if available. SearchUsage: type: object required: - returned - segmentsReturned - generation - retrievalMode - rerankOutcome - dropped - permissionFiltered properties: returned: type: integer description: The number of records returned. segmentsReturned: type: integer description: The total number of passages returned across all records. generation: type: number description: The version of the index used for this search. retrievalMode: type: string enum: - hybrid - semantic_failed_open - lexical_failed_open description: >- How results were retrieved. hybrid combines semantic and keyword search. The other values mean one of the two was unavailable and results came from the other. rerankOutcome: type: string description: Whether reranking was applied to the results, and if not, why. enum: - applied - disabled_by_deployment - disabled_by_request - provider_unavailable dropped: $ref: '#/components/schemas/SearchDrops' description: Counts of matches that were left out of the results. degraded: type: string enum: - rerank_unavailable - rewrite_skipped description: >- Present when part of the search pipeline was skipped, so results may be lower quality than usual. underfilled: type: boolean description: >- True if fewer results were returned than requested because there were not enough matches. permissionFiltered: type: boolean description: True if results were filtered to what the user can access. identities: type: object description: Which accounts from identity were used to check permissions. properties: applied: type: object description: The accounts that were applied, grouped by source. additionalProperties: type: array items: type: string unused: type: array description: Accounts you passed that did not match any searched source. items: type: object properties: source: type: string principal: type: string ErrorEnvelope: type: object required: - error properties: error: type: object required: - code - message - hint - retryable - requestId properties: code: type: string description: >- A stable error code you can handle in your code, such as REQUEST_INVALID. message: type: string description: A human-readable description of what went wrong. hint: type: string description: Suggested next step to resolve the error. retryable: type: boolean description: Whether retrying the same request may succeed. retryAfterMs: type: integer description: >- How long to wait before retrying, in milliseconds. Only present when retryable is true. requestId: type: string description: Include this ID when contacting Paragon support about a request. details: type: array description: >- Present on validation errors. Lists the fields that failed validation. items: type: object required: - field - issue properties: field: type: string description: The field that failed validation. issue: type: string description: What was wrong with the field. Segment: type: object required: - pointer - chunkId - text - relevancy - rerankScore properties: pointer: type: string description: >- Pass this to Read Segment Context to read the text around this passage. chunkId: type: string deprecated: true description: Deprecated. Use pointer instead. text: type: string description: The text of the matching passage. relevancy: type: number description: >- Rank-based score used to order passages in this response. Not comparable across requests. rerankScore: oneOf: - type: number - type: 'null' description: >- The reranker's score for this passage, or null if it was not reranked. SearchDrops: type: object required: - segmentsBeyondPoolCap - segmentsUnjoinable - segmentsNotSearchable - recordsBeyondTopK properties: segmentsBeyondPoolCap: type: integer description: Passages left out because the candidate pool was full. segmentsUnjoinable: type: integer description: Passages left out because they could not be matched to a record. segmentsNotSearchable: type: integer description: Passages left out because they are not currently searchable. recordsBeyondTopK: type: integer description: Records left out because they ranked below topK. responses: Error: description: The request failed. See the error object for details. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Your [Paragon User Token](/getting-started/installing-the-connect-sdk#setup) (JWT), which you can generate using your project's signing keys. ````