---
title: "Search files"
method: GET
path: "/files"
tags: ["Files"]
---

# Search files

`GET /files`

## Request

- Base URL: `https://app.gc.ai/api/external/v1`
- URL: `https://app.gc.ai/api/external/v1/files`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/gc-ai/apis/gc-ai-external-api/docs/files/get.ts> (a function with typed inputs; its response is checked against the schema)

Hybrid (vector + keyword) search across accessible files. Results are ranked by relevance and capped at 100.

User-scoped keys search all files the user can read. Org-scoped keys search all non-access-controlled files in the organization.

Pass `scope` (user-scoped keys only) to constrain the search to one of the three top-level meta-collections shown in the GC AI UI:
- `my-files`: files in the user's personal "My Files" tree
- `shared-with-me`: files explicitly shared with the user (and files inside shared folders)
- `organization`: files in the organization's "Organization Files" tree

Pass `project_id` (user- or org-scoped keys) to constrain the search to the files linked to one project, e.g. searching a project of contracts for specific terms. Mutually exclusive with `scope`. To list a project's files without a query, use `GET /projects/{id}/files` instead.

## Query parameters

- `q` string, required: Search query (required)
- `scope` 'my-files' | 'shared-with-me' | 'organization': Optional scope filter (user-scoped keys only). When omitted, searches all files the user can read. Mutually exclusive with `project_id`.
- `project_id` string, uuid: Optional project filter. Constrains the search to files linked to this project. Mutually exclusive with `scope`.

## Response `200`

Files matching the query, ranked by relevance

- FileSearchResponse
  - `files` SearchedFile[], required: Files matching the query, ranked by hybrid (vector + keyword) relevance. At most 100 results.
    - `id` string, uuid, required: Unique file identifier
    - `name` string, required: Original filename
    - `size` number, required: File size in bytes
    - `content_type` string, required: MIME type of the file
    - `status` 'extracting' | 'embedding' | 'ready' | 'failed', required: Current processing status
    - `folder_id` string, uuid, nullable, required: Parent folder ID, or null if the file is at the root
    - `created_at` string, required: ISO 8601 creation timestamp

## Other responses

- `400`: Missing or invalid query parameters, scope used with an org-scoped key, or both scope and project_id supplied
- `401`: Missing or malformed API key
- `403`: Invalid API key
- `404`: Project not found (when project_id is supplied)
- `429`: Rate limit exceeded. See [Rate Limits](https://docs.gc.ai/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
- `500`: Internal server error
- `503`: Service temporarily unavailable

---

[API](https://skmtc.dev/gc-ai/apis/gc-ai-external-api.md) - [All operations](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/revisions/2bbdfddf7107?raw)