> ## 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_metadata > Return ingestion-derived metadata for a file. Cost class: **fast**. ``representations`` answers "is this file actually searchable right now", which ``ingestion_status`` alone cannot: a file can be ingested while its graph generation is still building. ## OpenAPI ````yaml /openapi.json get /v1/workspaces/{workspace_id}/files/{file_id}/metadata 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}/metadata: get: tags: - files summary: get_file_metadata description: >- Return ingestion-derived metadata for a file. Cost class: **fast**. ``representations`` answers "is this file actually searchable right now", which ``ingestion_status`` alone cannot: a file can be ingested while its graph generation is still building. operationId: >- get_file_metadata_v1_workspaces__workspace_id__files__file_id__metadata_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/FileMetadata' 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: FileMetadata: additionalProperties: false description: >- Ingestion-derived metadata for a source file. ``representations`` answers "is this file actually searchable right now", which ``ingestion_status`` alone cannot: a file can be ingested while its graph generation is still building. ``outputs`` lists every live derivation (``retired_at IS NULL``) so a caller knows exactly what exists at each instant without racing against a re-ingestion in progress. properties: documents: items: $ref: '#/components/schemas/FileDocumentMetadata' title: Documents type: array duration_ms: anyOf: - type: integer - type: 'null' description: For audio/video; null for document formats. title: Duration Ms extracted_fields: items: $ref: '#/components/schemas/ExtractedField' title: Extracted Fields type: array file: $ref: '#/components/schemas/File' keywords: description: Lane-level keywords extracted during ingestion. items: type: string title: Keywords type: array lane: description: Which ingestion lane processed this file. title: Lane type: string last_error: anyOf: - $ref: '#/components/schemas/Error' - type: 'null' description: The most recent ingestion error, if any. media: anyOf: - $ref: '#/components/schemas/FileMediaMetadata' - type: 'null' outputs: items: $ref: '#/components/schemas/ArtifactOutputRef' title: Outputs type: array page_count: anyOf: - type: integer - type: 'null' description: For document formats; null for spreadsheets and media. title: Page Count representations: $ref: '#/components/schemas/RepresentationState' sheet_names: anyOf: - items: type: string type: array - type: 'null' description: For workbook formats; null for everything else. title: Sheet Names sheets: items: $ref: '#/components/schemas/FileSheetMetadata' title: Sheets type: array summary: anyOf: - type: string - type: 'null' description: Lane-level summary extracted during ingestion. title: Summary required: - file - lane title: FileMetadata 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 FileDocumentMetadata: additionalProperties: false properties: access_label: anyOf: - type: string - type: 'null' title: Access Label access_label_reason: anyOf: - type: string - type: 'null' title: Access Label Reason access_label_source: anyOf: - $ref: '#/components/schemas/AccessLabelSource' - type: 'null' category: title: Category type: string char_count: anyOf: - type: integer - type: 'null' description: Characters in the segment's markdown; null on older ingests. title: Char Count is_freeform_subcategory: default: false title: Is Freeform Subcategory type: boolean keywords: items: type: string title: Keywords type: array page_end: title: Page End type: integer page_start: title: Page Start type: integer path: title: Path type: string subcategory: title: Subcategory type: string summary: title: Summary type: string required: - category - subcategory - summary - page_start - page_end - path title: FileDocumentMetadata type: object ExtractedField: additionalProperties: false description: >- One field an extraction looked for. ``not_found`` is a real outcome with an entry, not a missing key: an extraction that silently omits what it could not find is indistinguishable from one that never looked. properties: citations: items: $ref: '#/components/schemas/Citation' title: Citations type: array confidence: anyOf: - type: number - type: 'null' title: Confidence path: description: JSON pointer into the schema. title: Path type: string status: enum: - found - not_found - ambiguous title: Status type: string value: anyOf: - type: string - type: integer - type: number - type: boolean - type: 'null' title: Value required: - path - status title: ExtractedField type: object File: additionalProperties: false description: >- A source file. The derived tree is platform-owned and has no CRUD surface. 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 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 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 title: File type: object 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 FileMediaMetadata: additionalProperties: false properties: duration_ms: title: Duration Ms type: integer frame_count: default: 0 title: Frame Count type: integer frames_dir: anyOf: - type: string - type: 'null' title: Frames Dir keywords: items: type: string title: Keywords type: array marlin_events: items: $ref: '#/components/schemas/FileMarlinEvent' title: Marlin Events type: array marlin_summary: default: '' title: Marlin Summary type: string modality: enum: - audio - video title: Modality type: string speakers: items: $ref: '#/components/schemas/FileMediaSpeaker' title: Speakers type: array speech_segment_count: default: 0 title: Speech Segment Count type: integer summary: default: '' title: Summary type: string timeline_path: title: Timeline Path type: string transcript_path: title: Transcript Path type: string required: - modality - duration_ms - timeline_path - transcript_path title: FileMediaMetadata type: object ArtifactOutputRef: additionalProperties: false description: One thing a source file produced outside the file store. properties: created_at: format: date-time title: Created At type: string generation: description: The file version this output was produced from. title: Generation type: integer kind: $ref: '#/components/schemas/ArtifactOutputKind' output_id: format: uuid title: Output Id type: string path: title: Path type: string required: - output_id - kind - path - generation - created_at title: ArtifactOutputRef type: object RepresentationState: additionalProperties: false description: >- Whether each representation is current for a file. Answers "is this file actually searchable right now", which ``ingestion_status`` alone cannot: a file can be ingested while its graph generation is still building. properties: knowledge_graph: default: false title: Knowledge Graph type: boolean organized_files: default: false title: Organized Files type: boolean search_index: default: false title: Search Index type: boolean title: RepresentationState type: object FileSheetMetadata: additionalProperties: false properties: categories: items: $ref: '#/components/schemas/FileCategoryAssignment' title: Categories type: array char_count: anyOf: - type: integer - type: 'null' description: Characters in the tab's markdown; null on older ingests. title: Char Count column_count: default: 0 title: Column Count type: integer error: anyOf: - type: string - type: 'null' title: Error jsonl_path: anyOf: - type: string - type: 'null' title: Jsonl Path keywords: items: type: string title: Keywords type: array markdown_path: anyOf: - type: string - type: 'null' title: Markdown Path max_column: default: 0 title: Max Column type: integer max_row: default: 0 title: Max Row type: integer non_empty_cell_count: default: 0 title: Non Empty Cell Count type: integer parquet_path: anyOf: - type: string - type: 'null' title: Parquet Path row_count: default: 0 title: Row Count type: integer sheet_name: title: Sheet Name type: string summary: default: '' title: Summary type: string required: - sheet_name title: FileSheetMetadata 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 Citation: additionalProperties: false description: Where an extracted value was found, with optional quoted source text. properties: location: discriminator: mapping: json_pointer: $ref: '#/components/schemas/JsonPointer' page_region: $ref: '#/components/schemas/PageRegion' row_range: $ref: '#/components/schemas/RowRange' sheet_range: $ref: '#/components/schemas/SheetRange' table_region: $ref: '#/components/schemas/TableRegion' text_span: $ref: '#/components/schemas/TextSpan' propertyName: kind oneOf: - $ref: '#/components/schemas/PageRegion' - $ref: '#/components/schemas/SheetRange' - $ref: '#/components/schemas/TextSpan' - $ref: '#/components/schemas/RowRange' - $ref: '#/components/schemas/TableRegion' - $ref: '#/components/schemas/JsonPointer' title: Location source_text: anyOf: - type: string - type: 'null' title: Source Text required: - location title: Citation type: object 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 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 FileMarlinEvent: additionalProperties: false properties: end_ms: anyOf: - type: integer - type: 'null' title: End Ms start_ms: anyOf: - type: integer - type: 'null' title: Start Ms text: default: '' title: Text type: string title: FileMarlinEvent type: object FileMediaSpeaker: additionalProperties: false properties: id: title: Id type: string label: anyOf: - type: string - type: 'null' title: Label required: - id title: FileMediaSpeaker type: object ArtifactOutputKind: description: Where a derivation landed, for the deletion cascade. enum: - opensearch_doc - kg_document - derived_file title: ArtifactOutputKind type: string FileCategoryAssignment: additionalProperties: false properties: category: title: Category type: string is_freeform_subcategory: default: false title: Is Freeform Subcategory type: boolean subcategory: title: Subcategory type: string required: - category - subcategory title: FileCategoryAssignment type: object JsonPointer: additionalProperties: false description: An RFC 6901 pointer into a JSON source; an empty string means the root. properties: kind: const: json_pointer default: json_pointer title: Kind type: string pointer: pattern: ^(?:$|/) title: Pointer type: string required: - pointer title: JsonPointer type: object PageRegion: additionalProperties: false description: A region on a 1-based page. A bbox is a 4-point polygon. properties: kind: const: page_region default: page_region title: Kind type: string page: minimum: 1 title: Page type: integer polygons: items: items: maxItems: 2 minItems: 2 prefixItems: - type: number - type: number type: array minItems: 3 type: array title: Polygons type: array required: - page title: PageRegion type: object RowRange: additionalProperties: false description: A 0-based inclusive row run on a parquet table. properties: column: anyOf: - type: string - type: 'null' title: Column end_row: minimum: 0 title: End Row type: integer kind: const: row_range default: row_range title: Kind type: string start_row: minimum: 0 title: Start Row type: integer required: - start_row - end_row title: RowRange type: object SheetRange: additionalProperties: false description: A cell range on a spreadsheet sheet. properties: a1_range: title: A1 Range type: string kind: const: sheet_range default: sheet_range title: Kind type: string sheet: title: Sheet type: string required: - sheet - a1_range title: SheetRange type: object TableRegion: additionalProperties: false description: >- Rows and columns from a Parquet source, with reproducible SQL provenance. properties: columns: items: type: string title: Columns type: array exact: title: Exact type: boolean kind: const: table_region default: table_region title: Kind type: string matched_rows: default: 0 minimum: 0 title: Matched Rows type: integer row_ranges: items: $ref: '#/components/schemas/TableRowRange' title: Row Ranges type: array source_file_name: title: Source File Name type: string sql: title: Sql type: string required: - source_file_name - sql - exact title: TableRegion type: object TextSpan: additionalProperties: false description: A character span in derived text (optional page when known). properties: char_end: minimum: 0 title: Char End type: integer char_start: minimum: 0 title: Char Start type: integer kind: const: text_span default: text_span title: Kind type: string page: anyOf: - minimum: 1 type: integer - type: 'null' title: Page required: - char_start - char_end title: TextSpan type: object TableRowRange: additionalProperties: false description: Inclusive 0-based row range in a table source. properties: end: minimum: 0 title: End type: integer start: minimum: 0 title: Start type: integer required: - start - end title: TableRowRange type: object securitySchemes: APIKeyHeader: in: header name: X-API-Key type: apiKey ````