> ## Documentation Index > Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.json get /v1/workspaces/{workspace_id}/files/{file_id} openapi: 3.1.0 info: description: >- Document intelligence: parse, split, classify, extract, and ground files, or build a searchable workspace. Authenticate with ``X-API-Key``. title: NDI Platform API version: 0.1.0 servers: - url: https://ndi-api.nace.ai security: [] tags: [] paths: /v1/workspaces/{workspace_id}/files/{file_id}: get: tags: - files summary: get_file description: >- 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. operationId: get_file_v1_workspaces__workspace_id__files__file_id__get parameters: - in: path name: file_id required: true schema: format: uuid title: File Id type: string - description: Workspace identifier. in: path name: workspace_id required: true schema: description: Workspace identifier. format: uuid title: Workspace Id type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/FileDetail' description: Successful Response '504': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Gateway Timeout default: content: application/json: example: error: code: invalid_request detail: null message: >- Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false schema: $ref: '#/components/schemas/ErrorEnvelope' description: >- Typed error envelope used by every 4xx and 5xx. ``error.code`` distinguishes the failure; HTTP status is a consequence of the code. security: - APIKeyHeader: [] components: schemas: FileDetail: additionalProperties: false description: >- 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. properties: access_label: anyOf: - type: string - type: 'null' description: Exactly one label, or null when the workspace declares none. title: Access Label access_label_source: anyOf: - $ref: '#/components/schemas/AccessLabelSource' - type: 'null' category: anyOf: - type: string - type: 'null' description: Null until categorised. title: Category created_at: format: date-time title: Created At type: string download_url: description: Time-limited presigned GET URL that saves the file's bytes to disk. title: Download Url type: string download_url_expires_at: description: When the presigned URLs stop being valid. format: date-time title: Download Url Expires At type: string expires_at: anyOf: - format: date-time type: string - type: 'null' description: When derived material for this file ages out. title: Expires At file_id: format: uuid title: File Id type: string file_name: title: File Name type: string file_type: title: File Type type: string graph_inclusion: default: auto description: >- 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. enum: - auto - include - exclude title: Graph Inclusion type: string ingested_at: anyOf: - format: date-time type: string - type: 'null' title: Ingested At ingested_hash: anyOf: - type: string - type: 'null' description: >- Content hash at the last successful ingestion. Null with ingested_at means never ingested. title: Ingested Hash ingestion_status: $ref: '#/components/schemas/IngestionStatus' labels: additionalProperties: type: string description: Caller-supplied metadata. title: Labels type: object observed_hash: title: Observed Hash type: string path: title: Path type: string preview_url: description: Time-limited presigned GET URL that a browser renders inline. title: Preview Url type: string size_bytes: title: Size Bytes type: integer updated_at: format: date-time title: Updated At type: string version: description: Starts at 1; increments on every content replacement. title: Version type: integer workspace_id: format: uuid title: Workspace Id type: string required: - file_id - workspace_id - path - file_name - file_type - size_bytes - observed_hash - ingestion_status - version - created_at - updated_at - download_url - preview_url - download_url_expires_at title: FileDetail type: object ErrorEnvelope: description: Every non-2xx body on ``/v1``. example: error: code: invalid_request detail: null message: Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false properties: error: $ref: '#/components/schemas/Error' required: - error title: ErrorEnvelope type: object AccessLabelSource: description: |- 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. enum: - inherited - classified - mirrored title: AccessLabelSource type: string IngestionStatus: description: >- 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. enum: - discovered - queued - ingesting - ingested - stale - expired - failed - not_required title: IngestionStatus type: string Error: description: The error object, per spec 12 §1.8. properties: code: $ref: '#/components/schemas/ErrorCode' detail: anyOf: - additionalProperties: true type: object - type: 'null' description: Structured payload, when the code carries one. title: Detail message: description: Human- and model-readable; says what to do differently. title: Message type: string request_id: description: Per-request correlation id; matches the ``X-Request-Id`` header. title: Request Id type: string retryable: description: Whether retrying the identical request could succeed. title: Retryable type: boolean required: - code - message - retryable - request_id title: Error type: object ErrorCode: description: |- Every error the ``/v1`` surface can return. Clients must treat this as an **open** enum: a new member is an additive change (spec 12 §9), and a client that crashes on an unknown code makes every future error a breaking change. enum: - invalid_request - unsupported_file_type - file_too_large - invalid_schema - invalid_sql - invalid_path_prefix - command_not_permitted - batch_too_large - domain_validation_failed - default_label_required - wait_required_for_zero_retention - workspace_not_found - file_not_found - job_not_found - upload_not_found - node_not_found - schema_not_found - domain_not_found - session_not_found - access_label_not_found - path_conflict - schema_version_conflict - access_label_name_taken - workspace_name_taken - access_label_in_use - upload_expired - file_not_ingested - workspace_deleting - workspace_not_deletable - ingestion_in_progress - job_not_cancellable - confirmation_required - domain_not_published - domain_in_use - reserved_domain_slug - kg_not_built - kg_build_in_progress - session_busy - range_not_satisfiable - result_expired - access_denied - access_backstop_violation - access_mode_not_implemented - rate_limited - concurrency_limit_reached - quota_exceeded - corrupt_file - zero_byte_file - encrypted_file - parse_failed - ocr_failed - conversion_failed - sheetless_workbook - unplayable_media - unclassified_pages - job_cancelled - job_timeout - upstream_unavailable - internal_error - unauthorized - not_implemented title: ErrorCode type: string securitySchemes: APIKeyHeader: in: header name: X-API-Key type: apiKey ````