---
title: "Search Files by Keyword"
method: POST
path: "/v2/files/search"
tags: ["Files"]
---

# Search Files by Keyword

`POST /v2/files/search`

Search files by keyword. The scope of the search is controlled by the request body:

- Provide `fileIds` to limit the search to specific files.
- Provide `companyId` to limit the search to files associated with a specific company.
- Omit both to search across your entire account.

`fileIds` and `companyId` are mutually exclusive.

Returns up to `limit` files ordered by relevance. Prompts with no strong matches may
still return low-relevance results.

Each result contains a matched file and a single representative excerpt (a matching
passage from that file). Even if a file contains multiple matching passages, it appears
exactly once in the response with one excerpt.

## Request body

- union
  - object — Search all files in the org, or limit to specific file IDs.
    - `prompt` string, required — The search query. Returns up to `limit` files ordered by relevance. Prompts with no strong matches may still return low-relevance results.
    - `fileIds` integer[] — Limit search to these specific files. Omit for org-wide search.
    - `limit` integer — Maximum number of files to return.
  - object — Search files associated with a specific company.
    - `prompt` string, required — The search query. Returns up to `limit` files ordered by relevance. Prompts with no strong matches may still return low-relevance results.
    - `companyId` integer — Restrict search to files associated with this company.
    - `limit` integer — Maximum number of files to return.

## Response `201`

Created

- FilesKeywordSearchResult — Results of a keyword search over files.
  - `data` FilesSearchResult[], required — Matching file results, one per file, ordered by relevance.
    - `file` object, required — The matched file.
      - `id` integer, required — The file's unique identifier.
      - `name` string, required — The file name.
    - `pageNumber` integer, nullable, required — The page where this passage was found. Null for files without page structure.
    - `preview` string, required — The matching passage, up to 2,000 characters.

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `default` — Errors

---

[API](https://skmtc.net/affinity/apis/affinity-api-v2.md) · [All operations](https://skmtc.net/affinity/apis/affinity-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/affinity/affinity-api-v2/revisions/4c2891c31b7f/schema)