# List Files

`lawmatics_list-files` · Lawmatics MCP tool · Files

List file metadata from Lawmatics with optional pagination, sorting, and a single-field filter. Rows carry a `relationships` envelope of to-one {id,type} pointers (documentable owner, folder, parent folder). To list the files belonging to one record (matter, contact, company, invoice, …), filter on documentable_id with that record's id. You can also filter on created_at / updated_at by date. Returns metadata only — use download-file to retrieve a file's contents.

## Input

- **page** `integer` (> 0) — Page number (1-based)
- **filter** `object` — Optional single-field filter; one filter at a time
  - **field** `string` (required, enum: "documentable_id", "created_at", "updated_at") — Field to filter on: documentable_id (numeric id of the record — matter/prospect, contact, company, invoice, … — the file belongs to; the way to list one record's files), created_at, or updated_at (dates)
  - **operator** `string` (enum: "=", "!=", "<", "<=", ">", ">=", "null", "not_null") — Comparison operator. Omit to use the Lawmatics per-field default (= for documentable_id). Use = for documentable_id and a range operator (e.g. >=) for created_at / updated_at
  - **value** `string` (required) — Value to compare against (ignored for null / not_null operators)
- **sortBy** `string` (enum: "id", "created_at", "updated_at") — Column to sort by
- **sortOrder** `string` (enum: "asc", "desc") — Sort direction; ascending or descending

## Output

- **files** `array` (required) — Files on the requested page (metadata only — use download-file to retrieve contents)
  - **[]** `object`
    - **id** `string` (required) — Unique ID of the file
    - **name** `string` (required) — Display name of the file as stored in Lawmatics
    - **fileName** `string | null` (required) — Original uploaded file name (e.g. report.pdf); null if not reported
    - **contentType** `string | null` (required) — MIME type of the file (e.g. application/pdf); null if not reported
    - **size** `number | null` (required) — File size in bytes; null if not reported
    - **createdAt** `string | null` (required) — When the file was created, as an ISO 8601 timestamp; null if unknown
    - **updatedAt** `string | null` (required) — When the file was last updated, as an ISO 8601 timestamp; null if unknown
    - **relationships** `object` (required) — To-one JSON:API relationship pointers as {id,type} stubs. Not materialized — follow a pointer by calling that resource's own tool (e.g. type 'prospect' -> get-matter, type 'folder' -> get-folder).
      - **documentable** `object | null` (required) — Owning record pointer (matter/prospect, contact, company, or firm); null when the file has no owner
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference (e.g. "user", "contact", "prospect", "firm"); resolve it by calling that resource's own get/find tool — this pointer is not materialized
      - **folder** `object | null` (required) — Folder the file lives in; null when at the root / unfiled
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference (e.g. "user", "contact", "prospect", "firm"); resolve it by calling that resource's own get/find tool — this pointer is not materialized
      - **parentFolder** `object | null` (required) — Parent folder pointer; null when the file is not nested under a folder
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference (e.g. "user", "contact", "prospect", "firm"); resolve it by calling that resource's own get/find tool — this pointer is not materialized
- **pagination** `object | null` (required) — Pagination metadata from the API response; null when the endpoint returns no meta envelope
  - **totalPages** `number | null` (required) — Total number of pages available
  - **limitPerPage** `number | null` (required) — Maximum files returned per page; null if not reported
  - **totalEntries** `number | null` (required) — Total number of files across all pages