curl --request GET \
--url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/files/{file_id} \
--header 'X-API-Key: <api-key>'{
"created_at": "2023-11-07T05:31:56Z",
"download_url": "<string>",
"download_url_expires_at": "2023-11-07T05:31:56Z",
"file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"file_name": "<string>",
"file_type": "<string>",
"ingestion_status": "discovered",
"observed_hash": "<string>",
"path": "<string>",
"preview_url": "<string>",
"size_bytes": 123,
"updated_at": "2023-11-07T05:31:56Z",
"version": 123,
"workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"access_label": "<string>",
"access_label_source": "inherited",
"category": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"graph_inclusion": "auto",
"ingested_at": "2023-11-07T05:31:56Z",
"ingested_hash": "<string>",
"labels": {}
}{
"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
}
}get_file
Return a file plus a short-lived presigned download URL. Cost class: fast.
No separate GET .../content route: the presigned URL keeps raw bytes
off the API path. The URL expires after DOWNLOAD_URL_TTL_SECONDS
seconds; fetch it promptly.
A direct read of a named file is the one case where hard denial
(403 access_denied) is correct: the caller named the file, so there
is nothing to narrow and nothing to infer — they already knew it existed.
curl --request GET \
--url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/files/{file_id} \
--header 'X-API-Key: <api-key>'{
"created_at": "2023-11-07T05:31:56Z",
"download_url": "<string>",
"download_url_expires_at": "2023-11-07T05:31:56Z",
"file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"file_name": "<string>",
"file_type": "<string>",
"ingestion_status": "discovered",
"observed_hash": "<string>",
"path": "<string>",
"preview_url": "<string>",
"size_bytes": 123,
"updated_at": "2023-11-07T05:31:56Z",
"version": 123,
"workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"access_label": "<string>",
"access_label_source": "inherited",
"category": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"graph_inclusion": "auto",
"ingested_at": "2023-11-07T05:31:56Z",
"ingested_hash": "<string>",
"labels": {}
}{
"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
Response
Successful Response
A source file plus short-lived presigned URLs for its bytes.
No separate GET .../content route: a presigned URL keeps raw bytes
off the API path and avoids charging for a second network hop inside the
platform. Both URLs expire after DOWNLOAD_URL_TTL_SECONDS seconds;
fetch them promptly.
The two differ only in the response headers S3 returns: download_url
saves to disk, preview_url renders in place under the file's real
media type. One URL cannot do both — a browser decides from the headers.
Time-limited presigned GET URL that saves the file's bytes to disk.
When the presigned URLs stop being valid.
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 Time-limited presigned GET URL that a browser renders inline.
Starts at 1; increments on every content replacement.
Exactly one label, or null when the workspace declares none.
Which mechanism produced a document's label.
The default_label fallback records as inherited, so an audit can
tell a real classification from a fallback.
inherited, classified, mirrored Null until categorised.
When derived material for this file ages out.
This file's knowledge-graph inclusion policy, not its effective membership. 'auto' defers to the workspace's KG exclusion rules; 'include'/'exclude' override them for this one file. A file excluded by a workspace rule still reads 'auto' here, so this does not on its own tell an excluded file from one whose graph is not built yet — read representations.knowledge_graph for whether a build has covered it.
auto, include, exclude Content hash at the last successful ingestion. Null with ingested_at means never ingested.
Caller-supplied metadata.
Show child attributes
Show child attributes