curl --request POST \
--url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/tools/file-metadata \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"path": "<string>"
}
'{
"file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"ingestion_status": "discovered",
"path": "<string>",
"size_bytes": 123,
"components": [
{
"kind": "section",
"name": "<string>",
"queryable": true,
"readable": true,
"approx_bytes": 123,
"char_count": 123,
"column_count": 123,
"columns": [
{
"data_type": "<string>",
"name": "<string>",
"distinct_count": 123,
"max_value": "<string>",
"min_value": "<string>",
"null_count": 123,
"sample_values": [
"<string>"
],
"sum_value": "<string>",
"top_values": [
{
"count": 123,
"value": "<string>"
}
],
"top_values_coverage": 123
}
],
"columns_truncated": true,
"error": "<string>",
"page_end": 123,
"page_start": 123,
"row_count": 123,
"summary": "",
"table_name": "<string>"
}
],
"ingestion_error": "<string>",
"kind": "<string>",
"page_count": 123,
"summary": "",
"tab_count": 123,
"total_approx_bytes": 123,
"total_chars": 123
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}file_metadata
Return the metadata of one uploaded file without opening it.
Cost class: fast.
path names an uploaded source file — the only namespace this tool
serves. The response describes the file’s public components (a pdf’s
sections, a spreadsheet’s tabs, a recording, an image, or the raw upload
itself) with sizes, page or row extents, summaries, per-component
readable / queryable capability flags — and, for queryable tabs,
the column schema with its profiled statistics (columns: names, SQL
types, null/distinct counts, value ranges, numeric sums, and a bounded
value census for low-cardinality columns), so a caller can aim
query-tables at the right tabs without a probe query. The top-level summary /
keywords are the primary segment’s only — per-component detail lives on
the components — and fields with nothing to say are absent, not null. No
workspace-internal path appears anywhere; a workspace-internal path in the
request is refused with invalid_request naming the uploaded file to use
instead.
This is the decide step of the exploration loop: folder_metadata
(or a search tool) locates a file; file_metadata says what is inside
it, how big each component is, and which content tool applies (a
readable component suits read_file, a queryable one suits
qa_file); then act — scoped to one component by name when only that
section or tab matters.
An un-ingested file answers 200 with its ingestion_status and no
components — exactly what a caller needs to decide what to do next; a
failed one carries ingestion_error with the recorded reason.
curl --request POST \
--url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/tools/file-metadata \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"path": "<string>"
}
'{
"file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"ingestion_status": "discovered",
"path": "<string>",
"size_bytes": 123,
"components": [
{
"kind": "section",
"name": "<string>",
"queryable": true,
"readable": true,
"approx_bytes": 123,
"char_count": 123,
"column_count": 123,
"columns": [
{
"data_type": "<string>",
"name": "<string>",
"distinct_count": 123,
"max_value": "<string>",
"min_value": "<string>",
"null_count": 123,
"sample_values": [
"<string>"
],
"sum_value": "<string>",
"top_values": [
{
"count": 123,
"value": "<string>"
}
],
"top_values_coverage": 123
}
],
"columns_truncated": true,
"error": "<string>",
"page_end": 123,
"page_start": 123,
"row_count": 123,
"summary": "",
"table_name": "<string>"
}
],
"ingestion_error": "<string>",
"kind": "<string>",
"page_count": 123,
"summary": "",
"tab_count": 123,
"total_approx_bytes": 123,
"total_chars": 123
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}Authorizations
Path Parameters
Workspace identifier.
Body
Request body for file-metadata. path names an uploaded source file.
1 - 1024Response
Successful Response
Response body for file-metadata — everything about one uploaded file,
with no workspace-internal path anywhere.
summary is the file's primary segment's — the first logical
document's for the document lane, the first summarized sheet's for
tables — capped at FILE_SUMMARY_MAX_CHARS, never a concatenation across
components (each component still carries its own).
total_chars is a real character count and is only present when every
text component carries one (new ingests); total_approx_bytes is the
byte-based fallback that is always honest about being an estimate. An
un-ingested file answers 200 with its ingestion_status and no
components; a failed one additionally carries ingestion_error —
metadata is exactly what a caller needs to decide what to do next with
such a file.
The only thing that says whether a file is searchable.
expired cannot be derived from the hash pair: retention clears
ingested_hash, so an aged-out file and a never-ingested file look
identical. They call for different customer actions, so the status carries
the distinction the hashes cannot.
discovered, queued, ingesting, ingested, stale, expired, failed, not_required Byte size of the uploaded source object.
One public component of an uploaded file: a pdf section, a spreadsheet tab, an image, or the raw upload itself.
readable / queryable are the capability flags that say which content
tool applies to this component. char_count is a real character count
when ingestion measured one; approx_bytes is the honest byte fallback
(the size of the component's text representation) — the two are never
conflated. error passes through a per-tab ingestion degradation: such a
component stays visible but has no readable or queryable content.
- FileComponentInfo
- MediaComponentInfo
Show child attributes
Show child attributes
Why ingestion failed, when the ledger recorded a reason.
Ingestion lane (document / table / media), when known.