---
title: "Check file existence and get metadata headers"
method: HEAD
path: "/v1/files/{file_id}"
tags: ["Files"]
---

# Check file existence and get metadata headers

`HEAD /v1/files/{file_id}`

Lightweight existence check and metadata retrieval. Returns the same metadata as `GET /{file_id}` but as HTTP response headers and with no body — useful for existence checks and ETag-based conditional requests without transferring file content. Mirrors S3 `HeadObject` semantics. Headers returned: `X-File-Id`, `X-File-Mime-Type`, `X-File-Size`, `X-File-Etag`, `X-File-Namespace`, `X-File-Filename`, `X-File-Created-At`.

## Path parameters

- `file_id` string, required

## Query parameters

- `scope_id` string, required — Session / container identifier.
- `namespace` string — Namespace the file belongs to. Defaults to 'session'.

## Response `200`

File exists; metadata in response headers.

- unknown

## Other responses

- `401` — Unauthorized
- `404` — File not found.
- `422` — Validation Error

## Changes

- **2026-08-27** `4e828cf153c4` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/zylon-ai/apis/private-gpt-api/changes/v1/files/:file_id/head.md)

---

[API](https://skmtc.dev/zylon-ai/apis/private-gpt-api.md) · [All operations](https://skmtc.dev/zylon-ai/apis/private-gpt-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/zylon-ai/private-gpt-api/revisions/4e828cf153c4/schema)