---
title: "🛡️ Get files from your index."
method: GET
path: "/api/v1/index/file"
tags: ["Indexing"]
---

# 🛡️ Get files from your index.

`GET /api/v1/index/file`

Get one or more files from your index. Depending on the filetype, addtional
information will be returned about the entities that were extracted from
the file.
<!-- Leave this line empty -->
<br /><hr /><h3>🛡️ Requires Capabilities: <code>Indexing.Operate</code></h3>

## Query parameters

- `ids` string[]
- `library` string

## Response `200`

- File[]
  - `user` User, required
    - `userId` string, required
    - `cardinalId` string
    - `cachedCloudUser` object, required
      - `subscription` 'free' | 'early_adopter' | 'starter' | 'pro' | 'ultimate'
    - `cachedCloudUserAt` string, date-time
    - `enabled` boolean
    - `role` string, required
    - `designation` string
    - `activityStatus` string
    - `activityStatusUpdatedAt` string, date-time
    - `roles` RoleAssignment[], required
      - `id` number, required
      - `user` User, required — recursive
      - `role` string, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `deletedAt` string, date-time, required
    - `username` string
    - `password` string
    - `id` number, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `deletedAt` string, date-time, required
  - `run` Run, required
    - `runId` string, required
    - `file` File[]
    - `status` string, required
    - `id` number, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `deletedAt` string, date-time, required
  - `musicTrack` MusicTrack[]
    - `file` File, required — recursive
    - `artists` MusicArtist[], required
      - `tracks` MusicTrack[]
      - `releases` MusicRelease[]
        - `tracks` MusicTrack[]
        - `artist` MusicArtist — recursive
        - `artists` MusicArtist[]
        - `genres` MusicGenre[]
          - `releases` MusicRelease[]
          - `musicGenreId` string, required
          - `name` string
          - `id` number, required
          - `createdAt` string, date-time, required
          - `updatedAt` string, date-time, required
          - `deletedAt` string, date-time, required
        - `musicReleaseId` string, required
        - `title` string
        - `sortTitle` string
        - `metadata` MusicReleaseMetadata[]
          - `release` MusicRelease, required — recursive
          - `metadataType` object
          - `metadataFormat` object
          - `metaKey` string, required
          - `metaValue` string
          - `id` number, required
          - `createdAt` string, date-time, required
          - `updatedAt` string, date-time, required
          - `deletedAt` string, date-time, required
        - `thumbnails` MusicReleaseThumbnail[]
          - `thumbnailId` string, required
          - `absolutePath` string, nullable, required
          - `relativeSrc` string, nullable, required
          - `size` string, required
          - `format` string, required
          - `width` number, required
          - `height` number, required
          - `bytes` number, required
          - `release` MusicRelease, required — recursive
          - `id` number, required
          - `createdAt` string, date-time, required
          - `updatedAt` string, date-time, required
          - `deletedAt` string, date-time, required
        - `id` number, required
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `deletedAt` string, date-time, required
      - `musicArtistId` string, required
      - `name` string
      - `sortName` string
      - `metadata` MusicArtistMetadata[]
        - `musicTrack` MusicArtist, required — recursive
        - `metadataType` object
        - `metadataFormat` object
        - `metaKey` string, required
        - `metaValue` string
        - `id` number, required
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `deletedAt` string, date-time, required
      - `id` number, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `deletedAt` string, date-time, required
    - `release` MusicRelease, required
      - `tracks` MusicTrack[]
      - `artist` MusicArtist
        - `tracks` MusicTrack[]
        - `releases` MusicRelease[]
        - `musicArtistId` string, required
        - `name` string
        - `sortName` string
        - `metadata` MusicArtistMetadata[]
          - `musicTrack` MusicArtist, required — recursive
          - `metadataType` object
          - `metadataFormat` object
          - `metaKey` string, required
          - `metaValue` string
          - `id` number, required
          - `createdAt` string, date-time, required
          - `updatedAt` string, date-time, required
          - `deletedAt` string, date-time, required
        - `id` number, required
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `deletedAt` string, date-time, required
      - `artists` MusicArtist[]
        - `tracks` MusicTrack[]
        - `releases` MusicRelease[]
        - `musicArtistId` string, required
        - `name` string
        - `sortName` string
        - `metadata` MusicArtistMetadata[]
          - `musicTrack` MusicArtist, required — recursive
          - `metadataType` object
          - `metadataFormat` object
          - `metaKey` string, required
          - `metaValue` string
          - `id` number, required
          - `createdAt` string, date-time, required
          - `updatedAt` string, date-time, required
          - `deletedAt` string, date-time, required
        - `id` number, required
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `deletedAt` string, date-time, required
      - `genres` MusicGenre[]
        - `releases` MusicRelease[]
        - `musicGenreId` string, required
        - `name` string
        - `id` number, required
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `deletedAt` string, date-time, required
      - `musicReleaseId` string, required
      - `title` string
      - `sortTitle` string
      - `metadata` MusicReleaseMetadata[]
        - `release` MusicRelease, required — recursive
        - `metadataType` object
        - `metadataFormat` object
        - `metaKey` string, required
        - `metaValue` string
        - `id` number, required
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `deletedAt` string, date-time, required
      - `thumbnails` MusicReleaseThumbnail[]
        - `thumbnailId` string, required
        - `absolutePath` string, nullable, required
        - `relativeSrc` string, nullable, required
        - `size` string, required
        - `format` string, required
        - `width` number, required
        - `height` number, required
        - `bytes` number, required
        - `release` MusicRelease, required — recursive
        - `id` number, required
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `deletedAt` string, date-time, required
      - `id` number, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `deletedAt` string, date-time, required
    - `musicTrackId` string, required
    - `title` string
    - `sortTitle` string
    - `trackNumber` number
    - `discNumber` number
    - `duration` number
    - `bitrate` number
    - `metadata` MusicTrackMetadata[]
      - `track` MusicTrack, required — recursive
      - `metadataType` object
      - `metadataFormat` object
      - `metaKey` string, required
      - `metaValue` string
      - `id` number, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `deletedAt` string, date-time, required
    - `history` MusicHistory[]
      - `playbackEntryId` string, required
      - `progress` number, required
      - `track` MusicTrack, required — recursive
      - `queueItem` PlaybackQueueItem
        - `queueItemId` string, required
        - `queue` PlaybackQueue, required
          - `queueId` string, required
          - `user` User, required
            - `userId` string, required
            - `cardinalId` string
            - `cachedCloudUser` object, required
              - …
            - `cachedCloudUserAt` string, date-time
            - `enabled` boolean
            - `role` string, required
            - `designation` string
            - `activityStatus` string
            - `activityStatusUpdatedAt` string, date-time
            - `roles` RoleAssignment[], required
              - …
            - `username` string
            - `password` string
            - `id` number, required
            - `createdAt` string, date-time, required
            - `updatedAt` string, date-time, required
            - `deletedAt` string, date-time, required
          - `type` object, required
          - `dynamicType` string, required
          - `libraries` Library[], required
            - `id` number, required
            - `libraryId` string, required
            - `name` string, required
            - `paths` string[], required
            - `user` User, required
              - …
            - `playbackQueues` PlaybackQueue[], required
            - `createdAt` string, date-time, required
            - `updatedAt` string, date-time, required
            - `deletedAt` string, date-time, required
          - `items` PlaybackQueueItem[]
          - `id` number, required
          - `createdAt` string, date-time, required
          - `updatedAt` string, date-time, required
          - `deletedAt` string, date-time, required
        - `history` MusicHistory — recursive
        - `mediaType` string, required
        - `mediaId` string, required
        - `position` number, required
        - `id` number, required
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `deletedAt` string, date-time, required
      - `user` User, required
        - `userId` string, required
        - `cardinalId` string
        - `cachedCloudUser` object, required
          - `subscription` 'free' | 'early_adopter' | 'starter' | 'pro' | 'ultimate'
        - `cachedCloudUserAt` string, date-time
        - `enabled` boolean
        - `role` string, required
        - `designation` string
        - `activityStatus` string
        - `activityStatusUpdatedAt` string, date-time
        - `roles` RoleAssignment[], required
          - `id` number, required
          - `user` User, required — recursive
          - `role` string, required
          - `createdAt` string, date-time, required
          - `updatedAt` string, date-time, required
          - `deletedAt` string, date-time, required
        - `username` string
        - `password` string
        - `id` number, required
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `deletedAt` string, date-time, required
      - `id` number, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `deletedAt` string, date-time, required
    - `id` number, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `deletedAt` string, date-time, required
  - `photo` Photo
    - `photoId` string, required
    - `file` File, required — recursive
    - `metadata` PhotoMetadata[], required
      - `photo` Photo, required — recursive
      - `metadataType` string
      - `metadataFormat` string
      - `metaKey` string, required
      - `metaValue` string
      - `id` number, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `deletedAt` string, date-time, required
    - `thumbnail` PhotoThumbnail[], required
      - `thumbnailId` string, required
      - `absolutePath` string, nullable, required
      - `relativeSrc` string, nullable, required
      - `size` string, required
      - `format` string, required
      - `width` number, required
      - `height` number, required
      - `bytes` number, required
      - `photo` Photo, required — recursive
      - `id` number, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `deletedAt` string, date-time, required
    - `variations` PhotoVariation[], required
      - `variationId` string, required
      - `absolutePath` string, nullable, required
      - `relativeSrc` string, nullable, required
      - `format` string, required
      - `bytes` number, required
      - `photo` Photo, required — recursive
      - `id` number, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `deletedAt` string, date-time, required
    - `photoAlbumEntries` PhotoAlbumEntry[], required
      - `photoAlbumEntryId` string, required
      - `photo` Photo, required — recursive
      - `photoAlbum` PhotoAlbum, required
        - `user` User
          - `userId` string, required
          - `cardinalId` string
          - `cachedCloudUser` object, required
            - `subscription` 'free' | 'early_adopter' | 'starter' | 'pro' | 'ultimate'
          - `cachedCloudUserAt` string, date-time
          - `enabled` boolean
          - `role` string, required
          - `designation` string
          - `activityStatus` string
          - `activityStatusUpdatedAt` string, date-time
          - `roles` RoleAssignment[], required
            - `id` number, required
            - `user` User, required — recursive
            - `role` string, required
            - `createdAt` string, date-time, required
            - `updatedAt` string, date-time, required
            - `deletedAt` string, date-time, required
          - `username` string
          - `password` string
          - `id` number, required
          - `createdAt` string, date-time, required
          - `updatedAt` string, date-time, required
          - `deletedAt` string, date-time, required
        - `photoAlbumId` string, required
        - `name` string, required
        - `entries` PhotoAlbumEntry[], required
        - `metadata` PhotoAlbumMetadata[], required
          - `photoAlbum` PhotoAlbum, required — recursive
          - `metaKey` string, required
          - `metaValue` string
          - `id` number, required
          - `createdAt` string, date-time, required
          - `updatedAt` string, date-time, required
          - `deletedAt` string, date-time, required
        - `id` number, required
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `deletedAt` string, date-time, required
      - `featured` boolean, required
      - `id` number, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `deletedAt` string, date-time, required
    - `timestamp` number, required
    - `takenAt` string, date-time, required
    - `takenOnDay` string, required
    - `modifiedAt` string, date-time, required
    - `width` number, required
    - `height` number, required
    - `orientation` string, required
    - `deviceMake` string, required
    - `deviceModel` string, required
    - `gpsLat` number, required
    - `gpsLng` number, required
    - `gpsLatRef` string, required
    - `gpsLngRef` string, required
    - `gpsAltitude` string, required
    - `gpsTime` string, required
    - `gpsDate` string, required
    - `id` number, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `deletedAt` string, date-time, required
  - `fileId` string, required
  - `jobTasks` JobTask[], required
    - `jobTaskId` string, required
    - `job` Job
      - `jobId` string, required
      - `user` User
        - `userId` string, required
        - `cardinalId` string
        - `cachedCloudUser` object, required
          - `subscription` 'free' | 'early_adopter' | 'starter' | 'pro' | 'ultimate'
        - `cachedCloudUserAt` string, date-time
        - `enabled` boolean
        - `role` string, required
        - `designation` string
        - `activityStatus` string
        - `activityStatusUpdatedAt` string, date-time
        - `roles` RoleAssignment[], required
          - `id` number, required
          - `user` User, required — recursive
          - `role` string, required
          - `createdAt` string, date-time, required
          - `updatedAt` string, date-time, required
          - `deletedAt` string, date-time, required
        - `username` string
        - `password` string
        - `id` number, required
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `deletedAt` string, date-time, required
      - `run` Run, required
        - `runId` string, required
        - `file` File[]
        - `status` string, required
        - `id` number, required
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `deletedAt` string, date-time, required
      - `type` 'album_art_thumbnails' | 'photo_variations' | 'photo_thumbnails', required
      - `status` 'draft' | 'preparing' | 'in_queue' | 'running' | 'paused' | 'canceled' | 'completed' | 'errored', required
      - `parameters` object
      - `tasks` JobTask[]
      - `completedTasks` number, required
      - `remainingTasks` number, required
      - `totalTasks` number, required
      - `completedAt` string, date-time, required
      - `errorMessage` string, required
      - `id` number, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `deletedAt` string, date-time, required
    - `file` File — recursive
    - `type` 'create_album_artwork_thumbnail' | 'create_photo_thumbnail' | 'heic_to_jpeg', required
    - `target` string, required
    - `status` 'draft' | 'in_queue' | 'running' | 'paused' | 'canceled' | 'completed' | 'errored', required
    - `completedAt` string, date-time, required
    - `errorMessage` string, required
    - `results` object
    - `id` number, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `deletedAt` string, date-time, required
  - `absolutePath` string, required
  - `relativePath` string, required
  - `mimeType` string
  - `extension` string, required
  - `app` string, required
  - `mediaType` string, required
  - `size` number, required
  - `mtime` string, date-time
  - `lastSeen` string, date-time, required
  - `id` number, required
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `deletedAt` string, date-time, required

## Other responses

- `401` — Possible reasons: The authorization token is invalid.
- `403` — Possible reasons: The user does not have sufficent capabilities.

## Changes

- **2026-04-13** `71bda9bfce4c` — 1 warning
  - removed the optional property `items/musicTrack/items/ratings` from the response with the `200` status
- **2026-04-12** `43cbfa2e8b43` — 1 info
  - added the optional property `items/musicTrack/items/ratings` to the response with the `200` status
- **2026-03-27** `eaf62ef2fb77` — 1 info
  - added the optional property `items/mtime` to the response with the `200` status
- **2026-03-21** `53ab8410d0eb` — 1 info
  - added the optional property `items/musicTrack/items/history/items/queueItem` to the response with the `200` status
- **2026-03-10** `1ec5a2e9d039` — 4 warning
  - removed the optional property `items/mtime` from the response with the `200` status
  - removed the optional property `items/musicTrack/items/artists/items/releases/items/releaseType` from the response with the `200` status
  - removed the optional property `items/musicTrack/items/history/items/queueItem` from the response with the `200` status
  - removed the optional property `items/musicTrack/items/release/releaseType` from the response with the `200` status

[Change history](https://skmtc.dev/cardinalapps/apis/cardinal-media-server-api/changes/api/v1/index/file/get.md)

---

[API](https://skmtc.dev/cardinalapps/apis/cardinal-media-server-api.md) · [All operations](https://skmtc.dev/cardinalapps/apis/cardinal-media-server-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cardinalapps/cardinal-media-server-api/revisions/71bda9bfce4c/schema)