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,
"category": "<string>",
"components": [
{
"kind": "section",
"name": "<string>",
"queryable": true,
"readable": true,
"categories": [
"<string>"
],
"column_count": 123,
"error": "<string>",
"key_terms": [
{}
],
"page_end": 123,
"page_start": 123,
"row_count": 123,
"summary": ""
}
],
"figures": [
{
"name": "<string>",
"page": 123,
"description": "<string>",
"text": ""
}
],
"ingestion_error": "<string>",
"job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "<string>",
"page_count": 123,
"summary": "",
"tab_count": 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
Describe one uploaded file without opening it: what it is, its category, and the parts you can ask about.
Cost class: fast.
path is the file’s full path relative to the workspace root, exactly
as it was uploaded and as folder-metadata, GET .../files and search
results (source_path) print it — for example
evidence/doc-7f83/contract.pdf. A bare file name (contract.pdf), a
folder, a file id, or a path that starts with the workspace id is not
found. file_not_found is final for that value: do not retry it or guess
variants — list the folder with folder-metadata (name_contains= a
part of the name) and use the path it prints.
The response gives the file’s category, a summary of its first
section or tab, page or tab counts, and its components: each section,
tab, image or recording with its own summary, categories, page range or
table shape, and key_terms — keywords whose role the source states
(who a name is, what a date marks). A recording reports its duration.
readable means qa-file can answer from the component’s text;
queryable means it is a table query-tables can compute over. Pass a
component’s name as component to scope either tool to it.
component narrows this response to one section or tab by name; a name
that matches nothing is refused with invalid_request listing the valid
names. A file that is not ingested yet answers 200 with its
ingestion_status and no components; a failed one carries
ingestion_error.
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,
"category": "<string>",
"components": [
{
"kind": "section",
"name": "<string>",
"queryable": true,
"readable": true,
"categories": [
"<string>"
],
"column_count": 123,
"error": "<string>",
"key_terms": [
{}
],
"page_end": 123,
"page_start": 123,
"row_count": 123,
"summary": ""
}
],
"figures": [
{
"name": "<string>",
"page": 123,
"description": "<string>",
"text": ""
}
],
"ingestion_error": "<string>",
"job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "<string>",
"page_count": 123,
"summary": "",
"tab_count": 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
Headers
Replaying a request with the same key returns the original job with 200, never a second job. The key is kept with the job for replay and never cleared, so it must not contain personal data.
200Path Parameters
Workspace identifier.
Body
Request body for file-metadata. path names one uploaded file.
The uploaded file's full path relative to the workspace root, exactly as it was uploaded and as listings and search results print it — e.g. evidence/doc-7f83/contract.pdf. Not a bare file name, a folder, a file id, or a path that starts with the workspace id.
1 - 1024Describe only this section or tab, named exactly as an unscoped call lists it.
Response
Successful Response
Response body for file-metadata — what one uploaded file is, without opening it.
summary is the summary of the file's first section or tab, never a
concatenation across components (each component carries its own). A file
that is not ingested yet answers 200 with its ingestion_status and no
components; a failed one also carries ingestion_error.
The uploaded file's id, as the files endpoints address it.
Where the file is in ingestion; a file that is not ingested has no components yet.
discovered, queued, ingesting, ingested, stale, expired, failed, not_required The uploaded file's path relative to the workspace root, as requested.
Byte size of the uploaded source object.
The file's primary category path, when classified.
The file's sections, tabs, image or recording, in reading order.
One part of an uploaded file that can be asked about by name: a document section, a spreadsheet tab, an image, or the raw upload itself.
- FileComponentInfo
- MediaComponentInfo
Show child attributes
Show child attributes
PDFs: pictures inside the pages (seals, charts, photos, stamps), in page order; with component, only those on that component's pages. Empty for other files and for PDFs ingested before figures were recorded.
Show child attributes
Show child attributes
Why ingestion failed, when the ledger recorded a reason.
The external operation job; absent for commands inside a search job.
Ingestion lane (document / table / media), when known.
Pages in a paged document; absent for other files.
Summary of the file's first section or tab; each component has its own.
Tabs in a workbook; absent for other files.