---
title: "Native media metadata for one file"
method: POST
path: "/v1/filesystem/metadata"
tags: ["Files"]
---

# Native media metadata for one file

`POST /v1/filesystem/metadata`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/filesystem/metadata`
- Auth: HTTP bearer

Header-bounded native probe: images via ImageIO (a properties read,
never a full decode), audio/video via AVFoundation track format
descriptions (the moov read). Video dimensions are DISPLAY
dimensions (the track's preferredTransform applied), so rotated
phone video reads portrait; images apply EXIF orientation the same
way. Every fact field is optional — a file the probe cannot parse
(a text file, a .ply) answers just the echoed path, never an
error. Refuses credential-store paths and any symlinked component
(403), like every filesystem route.

## Request body

- object
  - `path` string, required: Absolute path (tilde expanded) of the file to probe

## Response `200`

Probe result; an absent field means the probe had no answer

- object
  - `path` string, required: The probed path (server-expanded), echoing the request
  - `pixelWidth` integer: Display pixel width (video applies preferredTransform; images apply EXIF orientation)
  - `pixelHeight` integer: Display pixel height
  - `codec` string: Human codec name (HEVC, H.264, AAC, PNG…); the raw FourCC when unmapped
  - `frameRate` number: Video nominal frame rate, fps
  - `sampleRate` integer: Audio sample rate, Hz
  - `channels` integer: Audio channel count
  - `colorModel` string: Image color model (RGB, Gray, CMYK…)
  - `bitDepth` integer: Image bits per component

## Other responses

- `403`: Path under a credential store, or resolving through a symlink
- `404`: File not found

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)