Get checklist validation results for a directory (folder)

GET

directories

{directoryId}

checklist-validation

curl --request GET \
  --url https://api.orion.file.ai/prod/v1/directories/{directoryId}/checklist-validation \
  --header 'x-api-key: <api-key>'

import requests

url = "https://api.orion.file.ai/prod/v1/directories/{directoryId}/checklist-validation"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.orion.file.ai/prod/v1/directories/{directoryId}/checklist-validation', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "pass": 1,
  "fail": 1,
  "checklists": [
    {
      "checklistId": "649e2d2d2d2d2d2d2d2d2d2e",
      "checklistName": "Customs clearance pack",
      "status": "fail",
      "summary": {
        "missing": 2,
        "complete": 3,
        "incomplete": 1
      },
      "missingSchemas": [
        {
          "schemaId": "649e2d2d2d2d2d2d2d2d2d2d",
          "schemaName": "Bill of Lading"
        }
      ]
    }
  ]
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/feature-disabled",
  "title": "Feature not enabled",
  "status": 403,
  "detail": "Checklist validation is not enabled for this workspace.",
  "instance": "/v1/{route}",
  "code": "FEATURE_DISABLED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [],
  "message": "Checklist validation is not enabled for this workspace.",
  "error": "Forbidden",
  "statusCode": 403
}

{
  "type": "https://errors.file.ai/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "Directory not found.",
  "instance": "/v1/{route}",
  "code": "NOT_FOUND",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [],
  "message": "Directory not found.",
  "error": "Not Found",
  "statusCode": 404
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "Invalid directoryId. Must be a valid ObjectId.",
  "instance": "/v1/{route}",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [],
  "message": "Invalid directoryId. Must be a valid ObjectId.",
  "error": "Unprocessable Entity",
  "statusCode": 422
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

Request · Response · Guide: Folders

More details

The evaluation runs when you call: there is no stored result to poll for and no “pending” state. A checklist is judged on the folder as it is at that moment.Path Parameters:

directoryId (required): The directory to evaluate

Query Parameters:

skipCache (optional, default false): Re-run the underlying queries instead of reading the cached result. The cache is invalidated whenever the folder’s contents change through this API, so the default is correct for almost every caller; pass true only when a change was made by another path and you need the folder re-read now. It is a heavy folder-tree query, so prefer the default. Accepts true, false, 1 or 0 — any other value is a 422.

Response:

pass / fail: how many entries in checklists passed and failed. Counts of checklists, NOT of documents. fail: 0 is the all-passed case.
checklists: one entry per checklist targeting the folder, each with checklistId, checklistName, status, summary and missingSchemas.

Each summary carries all three keys, 0 when unused:

missing: required document types absent from the folder
complete: present documents with every required field filled
incomplete: present documents with at least one required field empty

Notes:

A checklist passes when missing and incomplete are both 0.
missingSchemas names the document types behind missing (deduped, schemaId + schemaName). It is always present and empty on a passing checklist. Prefer it over inferring the types from the count.
A presence-only checklist (no field rules) reports complete: 0, incomplete: 0 and is judged on missing alone.
checklists: [] means no checklist targets this folder. It is NOT an all-passed result, and no other field distinguishes the two — check the array before reading fail: 0 as a pass.
A checklist with no name is returned as Untitled checklist.
directoryId is echoed back in canonical lowercase form regardless of the case you send.
This endpoint only reads. It never changes the folder, its files, or any checklist.

Authorizations

x-api-key

string

header

required

API key for authentication

Path Parameters

directoryId

string

required

Query Parameters

skipCache

boolean

default:false

Re-run the checklist queries instead of reading the cached result. Defaults to false. Accepts true, false, 1 or 0; any other value is rejected.

Example:

false

Response

The checklists targeting this folder, evaluated now. An empty checklists array means no checklist targets the folder.

directoryId

string

required

The directory that was evaluated, in canonical lowercase form.

Example:

"649e2d2d2d2d2d2d2d2d2d2d"

pass

number

required

How many entries in checklists passed. A count of checklists, not of documents.

Example:

1

fail

number

required

How many entries in checklists failed. A count of checklists, not of documents. 0 is the all-passed case.

Example:

1

checklists

object[]

required

One entry per checklist that targets this folder, evaluated live. Empty when no checklist targets the folder at all — there is no separate field for that case.

Show child attributes

Get checklist validation results for a directory (folder)

curl --request GET \
  --url https://api.orion.file.ai/prod/v1/directories/{directoryId}/checklist-validation \
  --header 'x-api-key: <api-key>'

import requests

url = "https://api.orion.file.ai/prod/v1/directories/{directoryId}/checklist-validation"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.orion.file.ai/prod/v1/directories/{directoryId}/checklist-validation', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "pass": 1,
  "fail": 1,
  "checklists": [
    {
      "checklistId": "649e2d2d2d2d2d2d2d2d2d2e",
      "checklistName": "Customs clearance pack",
      "status": "fail",
      "summary": {
        "missing": 2,
        "complete": 3,
        "incomplete": 1
      },
      "missingSchemas": [
        {
          "schemaId": "649e2d2d2d2d2d2d2d2d2d2d",
          "schemaName": "Bill of Lading"
        }
      ]
    }
  ]
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/feature-disabled",
  "title": "Feature not enabled",
  "status": 403,
  "detail": "Checklist validation is not enabled for this workspace.",
  "instance": "/v1/{route}",
  "code": "FEATURE_DISABLED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [],
  "message": "Checklist validation is not enabled for this workspace.",
  "error": "Forbidden",
  "statusCode": 403
}

{
  "type": "https://errors.file.ai/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "Directory not found.",
  "instance": "/v1/{route}",
  "code": "NOT_FOUND",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [],
  "message": "Directory not found.",
  "error": "Not Found",
  "statusCode": 404
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "Invalid directoryId. Must be a valid ObjectId.",
  "instance": "/v1/{route}",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [],
  "message": "Invalid directoryId. Must be a valid ObjectId.",
  "error": "Unprocessable Entity",
  "statusCode": 422
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

Get started

Endpoints

Get checklist validation results for a directory (folder)

Authorizations

Path Parameters

Query Parameters

Response