> ## Documentation Index > Fetch the complete documentation index at: https://docs.poelis.com/llms.txt > Use this file to discover all available pages before exploring further. # List files > Retrieve files by scope. ## Scopes Use exactly one primary scope: - `item_id` to list files linked to an item (optionally include linked property files) - `property_id` to list files linked to a property - `product_id` to list files in the product's workspace (use `has_links=true` to only keep linked files) - `workspace_id` to list files in the workspace ## Versioning `version` supports: - Omitted or null: draft - Integer (for example `5`): files as of that version - `baseline`: files as of the product baseline version For `workspace_id` scope, `version` is not supported. ## Filtering Supports name search (`q`), MIME type (`content_type`), uploader (`uploaded_by`), linked/unlinked (`has_links`), and pagination. ## OpenAPI ````yaml /openapi.json get /v1/public/files openapi: 3.1.0 info: title: Poelis Public API description: |2- Poelis Public API - REST endpoints for external clients and integrations. ## Authentication All endpoints require an API key in the `Authorization` header: ``` Authorization: Bearer poelis_api_... ``` Get your API key from the web application's API Keys section. ## Rate Limiting API requests are rate-limited per organization. Contact support for higher limits. ## Support For questions or issues, contact support@poelis.com version: 1.0.0 servers: - url: https://api.poelis.com description: Production - url: http://localhost:8000 description: Local security: [] paths: /v1/public/files: get: tags: - Files summary: List files description: |- Retrieve files by scope. ## Scopes Use exactly one primary scope: - `item_id` to list files linked to an item (optionally include linked property files) - `property_id` to list files linked to a property - `product_id` to list files in the product's workspace (use `has_links=true` to only keep linked files) - `workspace_id` to list files in the workspace ## Versioning `version` supports: - Omitted or null: draft - Integer (for example `5`): files as of that version - `baseline`: files as of the product baseline version For `workspace_id` scope, `version` is not supported. ## Filtering Supports name search (`q`), MIME type (`content_type`), uploader (`uploaded_by`), linked/unlinked (`has_links`), and pagination. operationId: list_files_v1_public_files_get parameters: - name: workspace_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Workspace ID scope examples: - 550e8400-e29b-41d4-a716-446655440000 title: Workspace Id description: Workspace ID scope - name: product_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Product ID scope examples: - 660e8400-e29b-41d4-a716-446655440000 title: Product Id description: Product ID scope - name: item_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Item ID scope examples: - 770e8400-e29b-41d4-a716-446655440000 title: Item Id description: Item ID scope - name: property_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Property ID scope examples: - 880e8400-e29b-41d4-a716-446655440000 title: Property Id description: Property ID scope - name: version in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Product version number (integer) or 'baseline'. Omit or null for draft. examples: - null title: Version description: >- Product version number (integer) or 'baseline'. Omit or null for draft. - name: include_property_files in: query required: false schema: type: boolean description: >- When item_id is provided, include files linked to the item's properties. default: false title: Include Property Files description: >- When item_id is provided, include files linked to the item's properties. - $ref: '#/components/parameters/Query' - name: content_type in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by exact MIME type. title: Content Type description: Filter by exact MIME type. - name: uploaded_by in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by uploader user ID. title: Uploaded By description: Filter by uploader user ID. - name: has_links in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Filter by linked/unlinked files. title: Has Links description: Filter by linked/unlinked files. - name: include_deleted in: query required: false schema: type: boolean description: Include soft-deleted files. default: false title: Include Deleted description: Include soft-deleted files. - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: Paginated list of files with metadata and current link usages. content: application/json: schema: $ref: '#/components/schemas/PublicFilesResponse' headers: x-request-id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' '400': description: Bad Request headers: x-request-id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' '401': description: Unauthorized - Invalid or missing API key headers: x-request-id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: unauthorized message: Invalid or missing API key '403': description: Forbidden - Access denied headers: x-request-id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: forbidden message: Access denied '404': description: Not found headers: x-request-id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: not_found message: Not found '422': description: Validation error - Invalid request body or parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: validation_error message: Invalid data format details: errors: - loc: - body - field_name msg: field required type: value_error.missing '429': description: Too many requests content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: rate_limit_exceeded message: Too many requests security: - API Key: [] components: parameters: Query: name: q in: query required: false description: Optional search query to filter results. schema: type: string Limit: name: limit in: query required: false description: Maximum number of items to return per page. Must be between 1 and 200. schema: type: integer default: 50 minimum: 1 maximum: 200 example: 50 Offset: name: offset in: query required: false description: >- Number of items to skip from the beginning of the result set. Used for pagination. schema: type: integer default: 0 minimum: 0 example: 0 schemas: PublicFilesResponse: properties: items: items: $ref: '#/components/schemas/PublicFile' type: array title: Items count: type: integer title: Count type: object required: - items - count title: PublicFilesResponse description: Response payload for listing files. example: count: 1 items: - content_type: application/pdf deleted: false description: >- Specification document for compressor performance and operating constraints. id: 990e8400-e29b-41d4-a716-446655440000 name: compressor-spec-v3.pdf originalFileName: compressor-spec-v3.pdf size_bytes: 245612 uploadedBy: id: auth0|550e8400-e29b-41d4-a716-446655440000 imageUrl: https://example.com/avatar.png userName: Jane Doe uploaded_at: '2026-04-01T10:11:12.123Z' used_in: - file_link_id: 890e8400-e29b-41d4-a716-446655440000 product_id: 660e8400-e29b-41d4-a716-446655440000 target_id: 770e8400-e29b-41d4-a716-446655440000 target_type: item userTitle: Compressor specification ErrorResponse: type: object properties: error: type: string description: Machine-readable error code (e.g. validation_error, item_not_found). message: type: string description: Human-readable error message. details: type: object description: >- Additional error context (optional). For validation errors, contains a list of field-level issues. nullable: true required: - error - message PublicFile: properties: id: type: string title: Id description: File ID name: type: string title: Name description: Original file name (legacy compatibility field) originalFileName: type: string title: Originalfilename description: Original file name userTitle: anyOf: - type: string - type: 'null' title: Usertitle description: Optional editable file title content_type: anyOf: - type: string - type: 'null' title: Content Type description: MIME type description: anyOf: - type: string - type: 'null' title: Description description: File description size_bytes: anyOf: - type: integer - type: 'null' title: Size Bytes description: File size in bytes uploadedAt: anyOf: - type: string - type: 'null' title: Uploadedat description: ISO 8601 upload timestamp uploadedBy: anyOf: - $ref: '#/components/schemas/PublicUser' - type: 'null' description: User who uploaded the file deleted: type: boolean title: Deleted description: Whether the file is soft-deleted used_in: items: $ref: '#/components/schemas/PublicFileUsage' type: array title: Used In description: Current file link placements for this file type: object required: - id - name - originalFileName - deleted title: PublicFile description: Public representation of a stored file. example: content_type: application/pdf deleted: false description: >- Specification document for compressor performance and operating constraints. id: 990e8400-e29b-41d4-a716-446655440000 name: compressor-spec-v3.pdf originalFileName: compressor-spec-v3.pdf size_bytes: 245612 uploadedBy: id: auth0|550e8400-e29b-41d4-a716-446655440000 imageUrl: https://example.com/avatar.png userName: Jane Doe uploaded_at: '2026-04-01T10:11:12.123Z' used_in: - file_link_id: 890e8400-e29b-41d4-a716-446655440000 product_id: 660e8400-e29b-41d4-a716-446655440000 target_id: 770e8400-e29b-41d4-a716-446655440000 target_type: item userTitle: Compressor specification PublicUser: properties: id: type: string title: Id description: User ID userName: type: string title: Username description: Display name imageUrl: anyOf: - type: string - type: 'null' title: Imageurl description: Avatar URL type: object required: - id - userName title: PublicUser description: >- User representation in public API responses (owner, createdBy, updatedBy). example: id: auth0|550e8400-e29b-41d4-a716-446655440000 imageUrl: https://example.com/avatar.png userName: Jane Doe PublicFileUsage: properties: file_link_id: type: string title: File Link Id description: File link ID product_id: type: string title: Product Id description: Product ID where the file is linked target_type: type: string enum: - item - property title: Target Type description: Linked target type target_id: type: string title: Target Id description: Linked target ID (item ID or property ID) property_type: anyOf: - type: string enum: - numeric - text - date - status - matrix - formula - type: 'null' title: Property Type description: Property type when target_type is property type: object required: - file_link_id - product_id - target_type - target_id title: PublicFileUsage description: Link usage metadata for a file. example: file_link_id: 890e8400-e29b-41d4-a716-446655440000 product_id: 660e8400-e29b-41d4-a716-446655440000 target_id: 770e8400-e29b-41d4-a716-446655440000 target_type: item headers: RequestId: description: >- Request correlation ID. Echoes the incoming `x-request-id` header or a server-generated ID. schema: type: string RateLimitLimit: description: Request limit for the current rate limit window. schema: type: integer RateLimitRemaining: description: Remaining requests in the current rate limit window. schema: type: integer RateLimitReset: description: Unix timestamp (seconds) when the current rate limit window resets. schema: type: integer securitySchemes: API Key: type: http scheme: bearer bearerFormat: API Key description: 'Enter your API key. Example: Bearer poelis_api_...' ````