NAnace
files

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.

Args: context: Resolved workspace plus the caller's access predicate. session: Database session. file_id: The file to fetch.

Returns: FileDetail including the presigned download_url.

Raises: PlatformError: file_not_found when the file does not exist. PlatformError: access_denied when the caller does not hold the required access label.

get/v1/workspaces/{workspace_id}/files/{file_id}

Request

Path parameters

file_idstring uuid required
workspace_idstring uuid required

Workspace identifier.

Response

Successful Response

file_idstring uuid required
workspace_idstring uuid required
pathstring required

Full path relative to the workspace root. Send this exact string wherever a tool takes path: tools match it exactly.

file_namestring required

The last segment of path, for display only. A tool given it as path answers file_not_found.

file_typestring required
size_bytesinteger required
observed_hashstring required
ingested_hashstring nullable

Content hash at the last successful ingestion. Null with ingested_at means never ingested.

ingestion_status'discovered' | 'queued' | 'ingesting' | 'ingested' | 'stale' | 'expired' | 'failed' | 'not_required' required

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.

ingested_atstring date-time nullable
versioninteger required

Starts at 1; increments on every content replacement.

categorystring nullable

Null until categorised.

access_labelstring nullable

Exactly one label, or null when the workspace declares none.

access_label_source'inherited' | 'classified' | 'mirrored'

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.

expires_atstring date-time nullable

When derived material for this file ages out.

graph_inclusion'auto' | 'include' | 'exclude'

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.

labelsobject

Caller-supplied metadata.

created_atstring date-time required
updated_atstring date-time required
download_urlstring required

Time-limited presigned GET URL that saves the file's bytes to disk.

preview_urlstring required

Time-limited presigned GET URL that a browser renders inline.

download_url_expires_atstring date-time required

When the presigned URLs stop being valid.

Changes

No recorded changes to this operation across all 1 revision of this API.