> ## 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 > Returns files of a single document type, 25 per page, ordered by filename. When you are displaying files on a public site, pass `hiddenFromPublic=false` so you only receive files approved for public display. Elevation Certificates appear here only once processing has finished. A certificate that is still processing, or that was canceled, is absent, so do not read an empty result straight after an upload as a failed upload. ## OpenAPI ````yaml /developers/v1/openapi.json get /api/v1/files openapi: 3.1.0 info: title: Forerunner Integration API v1 version: 1.0.0 description: >- Read and write floodplain data in Forerunner. This is the v1 contract; each version is documented separately and evolves on its own. v1 is the current version. It covers files, properties, records, and SI/SD, and is the one to build against. Its record endpoints handle `Log` records only; use v2 for any other record type. Every request needs an `Authorization: Bearer ` header. List endpoints return 25 results per page; page through them with `page` and read `pageInfo` for the totals. Every JSON response carries an `errors` array, empty when the request succeeded; the `401`, `403`, and `429` responses are plain text or HTML instead. Develop against the staging server, which is a separate account with separate API keys and separate data. Requests are rate limited per IP at the CDN. A request over the limit is answered with a `429` and an HTML body, not the JSON error shape. servers: - url: https://app.withforerunner.com description: Production - url: https://app.staging.withforerunner.com description: Staging, for development and testing security: - bearerAuth: [] tags: - name: Files description: >- Upload, retrieve, and update documents such as Elevation Certificates and permits. - name: Properties description: Query the properties in your account. - name: Records description: >- Read, create, update, and delete `Log` records. Other record types are available on v2. - name: SI/SD description: >- Track substantial improvement and substantial damage against your community's thresholds. paths: /api/v1/files: get: tags: - Files summary: List Files description: >- Returns files of a single document type, 25 per page, ordered by filename. When you are displaying files on a public site, pass `hiddenFromPublic=false` so you only receive files approved for public display. Elevation Certificates appear here only once processing has finished. A certificate that is still processing, or that was canceled, is absent, so do not read an empty result straight after an upload as a failed upload. operationId: listFiles parameters: - in: query name: fileType schema: type: string description: >- Filter files by document type name, such as `Elevation Certificate` or `Building Permit`. Must match a document type configured for your account; see [File types](/files/file-types), or ask your customer success rep which are available. example: Elevation Certificate required: true description: >- Filter files by document type name, such as `Elevation Certificate` or `Building Permit`. Must match a document type configured for your account; see [File types](/files/file-types), or ask your customer success rep which are available. - in: query name: page schema: type: integer minimum: 1 description: 1-based page number. List endpoints return 25 results per page. example: 1 - in: query name: hiddenFromPublic schema: description: >- `true` returns only files hidden from the public site, `false` only files visible on it. Omit to return both. Use `false` when displaying files publicly. type: string enum: - 'true' - 'false' description: >- `true` returns only files hidden from the public site, `false` only files visible on it. Omit to return both. Use `false` when displaying files publicly. - in: query name: externalSystemId schema: type: string description: >- Return only items your system recorded under this identifier. Files and SI/SD records enforce uniqueness, so those match at most one; `Log` records do not. It can be set when creating or updating the item, or by an integration with an external system such as Accela. example: EC-2024-0417 responses: '200': description: Success. `errors` is empty. content: application/json: schema: $ref: '#/components/schemas/V1FileListResponse' example: errors: [] pageInfo: page: 1 pageSize: 25 totalCount: 67 totalPages: 3 files: - id: f8a3b2c1-d4e5-4789-abcd-ef0123456789 url: >- https://demoville.app.withforerunner.com/files/f8a3b2c1-d4e5-4789-abcd-ef0123456789 downloadURL: >- https://demoville.app.withforerunner.com/view-file/f8a3b2c1-d4e5-4789-abcd-ef0123456789 publicURL: >- https://demoville.withforerunner.com/view-file/f8a3b2c1-d4e5-4789-abcd-ef0123456789 filename: 123_main_st_ec.pdf mimeType: application/pdf property: id: a1b2c3d4-e5f6-4890-abcd-ef0123456789 address: 123 Main St, Springfield, IL 62701 publicURL: >- https://demoville.withforerunner.com/properties/a1b2c3d4-e5f6-4890-abcd-ef0123456789 coordinates: - 39.7817 - -89.6501 parcel: id: f1e2d3c4-b5a6-4890-8cba-098765432109 address: 123 Main St, Springfield, IL 62701 parcelId: 12-34-567-890 '400': description: The request failed validation. `errors` names each field at fault. content: application/json: schema: anyOf: - $ref: '#/components/schemas/V1FileListResponse' - $ref: '#/components/schemas/APIResponse' example: errors: - message: Required field: fileType files: [] '401': description: >- Missing or invalid API key. The body is plain text, not the JSON error shape. '403': description: >- Blocked by our web application firewall, which answers with an HTML body rather than the JSON error shape. Most often caused by a client sending a `PostmanRuntime`, `python-requests`, or `HeadlessChrome` `User-Agent`; clear that header and retry. '429': description: >- Too many requests from your IP. Rate limiting is applied at the CDN, so the body is HTML rather than the JSON error shape. Back off and retry. components: schemas: V1FileListResponse: type: object properties: errors: type: array items: $ref: '#/components/schemas/APIError' description: >- Empty when the request succeeded. Otherwise one entry per failure, and the resource fields on the response are empty: `null` for single resources, `[]` for lists, with `pageInfo` omitted. example: [] pageInfo: $ref: '#/components/schemas/V1PageInfo' files: type: array items: $ref: '#/components/schemas/V1File' description: Up to 25 files for the requested page. required: - errors - files additionalProperties: false APIResponse: type: object properties: errors: type: array items: $ref: '#/components/schemas/APIError' description: >- Empty when the request succeeded. Otherwise one entry per failure, and the resource fields on the response are empty: `null` for single resources, `[]` for lists, with `pageInfo` omitted. example: [] required: - errors additionalProperties: false description: Every response carries an `errors` array alongside its resource fields. APIError: type: object properties: message: type: string description: Human-readable description of what went wrong. example: Required field: type: string description: The request field that caused the error, as a dot-separated path. example: data.type required: - message - field additionalProperties: false description: A single validation or processing failure. V1PageInfo: type: object properties: page: type: number description: The page that was returned. example: 1 pageSize: type: number description: Results per page. Always 25. example: 25 totalCount: type: number description: Total results matching the filters, across all pages. example: 67 totalPages: type: number description: Number of pages available. example: 3 required: - page - pageSize - totalCount - totalPages additionalProperties: false description: >- Pagination metadata for a list response. Present whenever the request succeeded, and omitted when it failed validation. example: page: 1 pageSize: 25 totalCount: 67 totalPages: 3 V1File: type: object properties: id: type: string description: UUID of the file in Forerunner. example: f8a3b2c1-d4e5-4789-abcd-ef0123456789 url: type: string description: Link to the file's page in Forerunner. Requires an account to open. example: >- https://demoville.app.withforerunner.com/files/f8a3b2c1-d4e5-4789-abcd-ef0123456789 downloadURL: type: string description: Direct download link. Requires an account to open. example: >- https://demoville.app.withforerunner.com/view-file/f8a3b2c1-d4e5-4789-abcd-ef0123456789 publicURL: description: >- Public download link. Null when the file is hidden from the public site. example: >- https://demoville.withforerunner.com/view-file/f8a3b2c1-d4e5-4789-abcd-ef0123456789 type: - string - 'null' filename: type: string description: The filename as uploaded. example: 123_main_st_ec.pdf mimeType: type: string description: The file's media type. example: application/pdf property: anyOf: - $ref: '#/components/schemas/V1FileProperty' - type: 'null' description: >- The property this file is attached to, or null when it is not attached to one. required: - id - url - downloadURL - publicURL - filename - mimeType - property additionalProperties: false description: A file stored in Forerunner. V1FileProperty: type: object properties: id: type: string description: UUID of the property in Forerunner. example: a1b2c3d4-e5f6-4890-abcd-ef0123456789 address: description: >- The property's fully qualified address. Null for properties that have no address on file. example: 123 Main St, Springfield, IL 62701 type: - string - 'null' publicURL: description: >- Link to the property's public profile page. Null when the property is hidden from the public site. example: >- https://demoville.withforerunner.com/properties/a1b2c3d4-e5f6-4890-abcd-ef0123456789 type: - string - 'null' coordinates: type: array prefixItems: - type: number - type: number items: false minItems: 2 maxItems: 2 description: '`[latitude, longitude]` in EPSG:4326 (WGS 84).' example: - 39.7817 - -89.6501 parcel: anyOf: - $ref: '#/components/schemas/V1Parcel' - type: 'null' description: >- The parcel this property sits on. Null for properties with no parcel on file. required: - id - address - publicURL - coordinates - parcel additionalProperties: false description: The property a file is attached to. V1Parcel: type: object properties: id: type: string description: UUID of the parcel in Forerunner. example: f1e2d3c4-b5a6-4890-8cba-098765432109 address: description: Address recorded on the parcel. example: 123 Main St, Springfield, IL 62701 type: - string - 'null' parcelId: description: >- The parcel's identifier, as issued by the assessor. Often the key used to match parcels in external, non-Forerunner systems. example: 12-34-567-890 type: - string - 'null' required: - id - address - parcelId additionalProperties: false description: The parcel a property sits on. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your account's API key, sent as `Authorization: Bearer `. Keys are issued per environment, so a staging key will not work against production. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.