> ## Documentation Index
> Fetch the complete documentation index at: https://withforerunner.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List Files

> Retrieve a paginated list of files

<ParamField path="GET" type="endpoint">
  /api/v1/files
</ParamField>

Retrieve a paginated list of files filtered by type.

## Query Parameters

<ParamField query="fileType" type="string" required>
  Filter files by document type name. The value must match an existing document type name configured for your account (e.g., `Elevation Certificate`, `Building Permit`). Contact your CS rep for available document types.
</ParamField>

<ParamField query="externalSystemId" type="string">
  Find file via it's `externalSystemId`. Since this value is unique, this will return exactly zero or one entry in the files array. `externalSystemId` can be set via the [Submit File](/developers/api/files/submit) or [Update File](/developers/api/files/update) API or through an integration with an external data source (such as Accela).
</ParamField>

<ParamField query="hiddenFromPublic" type="boolean">
  Filter by public visibility. `true` returns only private files, `false` returns only public files
</ParamField>

<ParamField query="page" type="integer">
  Page number for pagination. See [Pagination](/developers/api/overview#pagination).
</ParamField>

<Note>
  If displaying Forerunner data on a publicly accessible website, set `hiddenFromPublic=false` to ensure you only retrieve files approved for public display.
</Note>

## Response

<ResponseField name="files" type="array">
  Array of file objects (up to 25 per page)

  <Expandable title="File object properties">
    <ResponseField name="id" type="string">
      UUID uniquely identifying the file
    </ResponseField>

    <ResponseField name="filename" type="string">
      Original filename upon upload
    </ResponseField>

    <ResponseField name="mimeType" type="string">
      File format type (e.g., `application/pdf`, `image/png`)
    </ResponseField>

    <ResponseField name="url" type="string">
      URL for the file's internal Forerunner page. Requires user authentication.
    </ResponseField>

    <ResponseField name="downloadURL" type="string">
      URL for direct file download. Requires authentication.
    </ResponseField>

    <ResponseField name="publicURL" type="string">
      Public download URL. Absent if the file is hidden from public.
    </ResponseField>

    <ResponseField name="property" type="object | null">
      Associated property. Null if the file is not linked to a property. See [Property object](/developers/api/properties/list#response) for the object schema.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pageInfo" type="object">
  Pagination metadata. See [Pagination](/developers/api/overview#pagination).
</ResponseField>

<ResponseField name="errors" type="array">
  Array of error objects. See [Errors](/developers/api/overview#errors).
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://app.withforerunner.com/api/v1/files?fileType=Elevation%20Certificate&page=1" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "files": [
      {
        "id": "f8a3b2c1-d4e5-6789-abcd-ef0123456789",
        "filename": "123_main_st_ec.pdf",
        "mimeType": "application/pdf",
        "url": "https://app.withforerunner.com/files/f8a3b2c1-d4e5-6789-abcd-ef0123456789",
        "downloadURL": "https://app.withforerunner.com/files/f8a3b2c1-d4e5-6789-abcd-ef0123456789/download",
        "publicURL": "https://app.withforerunner.com/public/files/f8a3b2c1-d4e5-6789-abcd-ef0123456789",
        "property": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
          "address": "123 Main St, Springfield, IL 62701",
          "url": "https://app.withforerunner.com/properties/a1b2c3d4-e5f6-7890-abcd-ef0123456789",
          "publicURL": "https://app.withforerunner.com/public/properties/a1b2c3d4-e5f6-7890-abcd-ef0123456789",
          "coordinates": [39.7817, -89.6501],
          "parcel": {
            "id": "f1e2d3c4-b5a6-7890-dcba-098765432109",
            "parcelId": "12-34-567-890",
            "address": "123 Main St, Springfield, IL 62701"
          }
        }
      }
    ],
    "pageInfo": {
      "page": 1,
      "pageSize": 25,
      "totalCount": 67,
      "totalPages": 3
    },
    "errors": []
  }
  ```
</ResponseExample>