curl --request GET \
--url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/files \
--header 'X-API-Key: <api-key>'{
"items": [
{
"created_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>",
"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": {}
}
],
"total_count": 123,
"coverage": {
"labels_required": [
"<string>"
],
"request_access_hint": "<string>",
"restricted_candidates": 0
},
"next_cursor": "<string>"
}{
"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
}
}list_files
List source files with exact totals and access-filtered coverage.
Cost class: fast (structured-metadata predicates only; no index lookup).
The sanctioned completeness instrument: total_count is exact and
access-filtered; coverage says how many candidates the access gate
withheld and which labels would have been needed. A caller that cannot
reconcile total_count with their own ledger knows the gap is
labelled content rather than a missing file.
curl --request GET \
--url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/files \
--header 'X-API-Key: <api-key>'{
"items": [
{
"created_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>",
"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": {}
}
],
"total_count": 123,
"coverage": {
"labels_required": [
"<string>"
],
"request_access_hint": "<string>",
"restricted_candidates": 0
},
"next_cursor": "<string>"
}{
"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.
Query Parameters
Restrict to paths starting with this prefix.
Restrict to these ingestion statuses.
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 Restrict to these categories.
Restrict to these file extensions.
Only files updated after this timestamp.
Only files updated before this timestamp.
Opaque cursor from a previous page's next_cursor. Omit for the first page.
Rows per page.
1 <= x <= 200Response
Successful Response
A page of source files plus the access honesty block.
coverage reports how many candidates the access gate withheld and
which labels would have been needed to see them. A workspace that
declares no access labels always has an empty coverage; total_count
is always exact after filtering.
Show child attributes
Show child attributes
Exact, and filtered by the caller's access predicate.
What the access gate withheld, in counts and label names only.
Never a name, path, or fragment of withheld content. Naming the labels leaks nothing the caller cannot already read from the workspace config, and it turns "some results were withheld" into an actionable request.
Show child attributes
Show child attributes
Opaque; null means the last page.