---
title: "validateFile"
method: POST
path: "/v1/files/validations"
tags: ["File"]
---

# validateFile

`POST /v1/files/validations`

## Request

- Base URL: `https://file.sls.epilot.io`
- URL: `https://file.sls.epilot.io/v1/files/validations`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `token`

Validate an uploaded file against one or more document validation rules
(validation-rules-api rules with `input_type: document`).

The file is referenced either by its file entity id or, for an upload that has not been
saved as an entity yet (e.g. a journey upload in the temporary prefix), by its S3 reference.
The service collects an observation of the file - deterministic facts such as the sniffed
mime type, size, page count, image resolution, blank and password-protection detection -
and evaluates every rule against it with the shared validation rules engine.

The response carries one result per rule with a per-condition outcome (`pass`, `fail`,
`uncertain`, `skipped`), plus the observation the results were derived from. `status` is
`completed` for checks that finish synchronously; `pending` is reserved for check levels
that need asynchronous content extraction.

## Request body

- FileValidationRequest
  - `file` union, required: The file to validate - a saved file entity, or an uploaded object not saved as an entity yet.
    - object
      - `entity_id` union, required
        - string: Empty string (used when file ID not yet assigned)
        - string, uuid: Valid UUID v4
    - object
      - `s3ref` S3Ref, required
        - `bucket` string, required
        - `key` string, required
  - `rule_ids` string[], required: Document validation rules to evaluate. Rules of another input type are rejected.

## Response `200`

The validation result

- FileValidation
  - `id` string, required: Identifier of this validation run.
  - `status` 'completed' | 'pending' | 'failed' | 'skipped', required: `completed` when every rule was evaluated. `pending` is reserved for check levels that need asynchronous content extraction; `failed` when the observation could not be produced; `skipped` when document validation is not enabled for the organisation - the file was not read and `results` is empty, so callers treat the file as accepted.
  - `file` FileValidationFile, required: The file that was validated, with the identity facts collected from its content.
    - `entity_id` union
      - string: Empty string (used when file ID not yet assigned)
      - string, uuid: Valid UUID v4
    - `s3ref` S3Ref
      - `bucket` string, required
      - `key` string, required
    - `filename` string
    - `mime_type` string: Mime type detected from the file content, falling back to the declared type.
    - `size_bytes` integer
  - `observation` FileValidationObservation, required: Everything observed about the file, as passed to the validation rules engine.
    - `facts` FileValidationFacts, required: Deterministic properties of the file. A property that is absent could not be determined (for example the resolution of an image the service cannot decode); conditions that need it are skipped rather than failed.
      - `mime_type` string
      - `size_bytes` integer
      - `page_count` integer: Pages of a PDF; 1 for images.
      - `longer_edge_px` integer: Longer edge of an image in pixels.
      - `is_blank` boolean
      - `is_password_protected` boolean
    - `judgements` object: Content judgements keyed by condition id, produced by the document requirements check for `meetsCriteria` conditions at the `standard` and `advanced` levels. Absent when no content check ran (basic level, unsupported file, or the check did not finish within its budget).
    - `document_type` object: Document type detected by the content check, when it ran.
      - `slug` string
      - `confidence` number
  - `results` FileValidationRuleResult[], required
    - `rule_id` string, required
    - `rule_title` string
    - `level` 'basic' | 'standard' | 'advanced', required: The rule's check level.
    - `is_valid` boolean, required: True when every blocking condition passed or was skipped.
    - `failed_parts` string[]: Error messages of blocking conditions that failed.
    - `warnings` string[]: Error messages of advisory conditions that failed and of uncertain judgements.
    - `conditions` FileValidationConditionResult[], required
      - `id` string, required
      - `operator` string, required
      - `outcome` 'pass' | 'fail' | 'uncertain' | 'skipped', required
      - `blocking` boolean, required: True when this outcome makes the file invalid.
      - `message` string, required: The condition's configured error message.
      - `evidence` string
      - `explanation` string
  - `created_at` string, date-time, required

## Other responses

- `400`: Invalid request parameters or payload
- `401`: Authentication required or invalid credentials
- `403`: Insufficient permissions to access the resource
- `404`: The requested resource was not found
- `413`: The file is too large to validate
- `422`: The file could not be read
- `500`: An unexpected error occurred on the server

## Changes

- **2026-09-10** `ec4c7e522c33`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/epilot/apis/file-api/changes/v1/files/validations/post.md)

---

[API](https://skmtc.dev/epilot/apis/file-api.md) - [All operations](https://skmtc.dev/epilot/apis/file-api/llms.txt) - [OpenAPI document](https://skmtc.dev/epilot/apis/file-api/revisions/bc1aea5a570e?raw)