> ## Documentation Index > Fetch the complete documentation index at: https://developers.conveyour.com/llms.txt > Use this file to discover all available pages before exploring further. # List files > Returns files for the org. Supports filtering by folder, contact, MIME type, and keyword search. Returns up to 1000 files by default; use `page`/`per_page` for pagination. **Response shape:** `data` is an object with `count`, `page`, `pages` and `results`. It does **not** return `per_page`, `has_more` or `has_less`. ## OpenAPI ````yaml /api-reference/specs/files.json get /api/files openapi: 3.1.0 info: title: ConveYour API — Files description: Upload and manage files and file folders in ConveYour. version: 1.0.0 servers: - url: https://{subdomain}.conveyour.com description: Your organization's ConveYour instance variables: subdomain: default: acme description: >- Your organization's slug — the subdomain you sign in on. Replace `acme` with yours: if you sign in at `bigco.conveyour.com`, enter `bigco`. security: - conveyourToken: [] tags: - name: Files description: Upload and manage files and file folders in ConveYour. paths: /api/files: get: tags: - Files summary: List files description: >- Returns files for the org. Supports filtering by folder, contact, MIME type, and keyword search. Returns up to 1000 files by default; use `page`/`per_page` for pagination. **Response shape:** `data` is an object with `count`, `page`, `pages` and `results`. It does **not** return `per_page`, `has_more` or `has_less`. operationId: listAllFiles parameters: - name: folder_id in: query description: >- Filter to files in a specific folder. Pass `null` to return files with no folder assigned. schema: type: string - name: pid in: query description: Filter to a file by its public ID (PID). schema: type: string - name: contact_id in: query description: Filter to files associated with a specific contact. schema: type: string - name: type in: query description: Filter by file type. schema: type: string - name: mime_types in: query description: >- Filter by one or more MIME types. Pass as repeated query params: `mime_types[]=application/pdf&mime_types[]=image/png`. schema: type: array items: type: string - name: query in: query description: Search by filename (case-insensitive substring match). schema: type: string - name: page in: query description: >- Page number (1-based). When set, enables paginated response. Omit for a flat list (up to 1000 records). schema: type: integer - name: per_page in: query description: 'Items per page when `page` is set. Default: `50`.' schema: type: integer - $ref: '#/components/parameters/teams' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: oneOf: - type: array items: $ref: '#/components/schemas/File' description: A flat array, capped at the maximum record count. - type: object description: Returned instead when page is passed. properties: page: type: integer description: Current page. pages: type: integer description: Total pages. count: type: integer description: Total matching files. results: type: array items: $ref: '#/components/schemas/File' description: >- A flat array of files by default. Passing page switches the response to a paginated object with page / pages / count / results. example: status: ok message: success data: - id: 64a1b2c3d4e5f6a7b8c9d0e1 filename: safety-handbook.pdf url: https://cdn.filestackcontent.com/abc123 mimetype: application/pdf folder_id: null '403': $ref: '#/components/responses/ForbiddenToken' components: parameters: teams: name: teams[] in: query description: >- Team scope for the request, as one or more team ObjectIds. The brackets are required: PHP keeps only the last value for a repeated plain key, so `teams=A&teams=B` silently resolves to B alone. On requests with a JSON body you may send `teams` (no brackets) in the body instead. **Values that are not valid ObjectIds are silently ignored** — a mistyped team ID behaves as if no team was sent. See the [teams section of the API conventions guide](/guides/api-conventions#team-scoping). style: form explode: true schema: type: array items: type: string example: - 64a1b2c3d4e5f6a7b8c9d0ff schemas: Envelope: type: object description: The common response envelope shared by all ConveYour endpoints. properties: status: type: string enum: - ok - failed description: '`ok` on success, `failed` on error.' message: type: string description: Human-readable description of the result. data: description: >- The response payload — an object or an array depending on the endpoint. File: type: object description: >- A file record. Returns the stored attributes and adds url, user_name, contact_name, folder_id and folder_name. properties: id: type: string description: File ID. pid: type: string description: Public ID. org_id: type: string description: Owning organization. user_id: type: integer description: Uploader. url: type: string description: >- Computed per request — the full CDN URL. On write the stored value is the extracted Filestack hash. filename: type: string description: File name. mimetype: type: string description: MIME type. Required on create. contact_id: type: string description: Linked contact, if any. contact_name: type: string description: Computed per request; empty when no contact. user_name: type: string description: >- Computed per request; empty when no user. Added only by the list and get-by-id read paths; create and update return the raw record without it. folder_id: type: string description: Containing folder. folder_name: type: string description: >- Computed per request; null when not in a folder. Added only by the list and get-by-id read paths; create and update return the raw record without it. type: type: string description: File type. teams: type: array description: Teams the file is scoped to. created_at: type: integer description: Unix timestamp. updated_at: type: integer description: Unix timestamp. required: - filename - mimetype responses: ForbiddenToken: description: >- The token is missing, expired, or not permitted for this HTTP method. **This endpoint enforces no named permission**, so a 403 here never carries a `permission` field. content: application/json: example: status: failed message: Token is either expired or does not have the correct permissions data: [] securitySchemes: conveyourToken: type: apiKey in: header name: x-conveyour-token description: >- Your API key token. Contacts endpoints require a **Server-only — Full API** key — see [Authentication](/quickstart). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.