> ## Documentation Index > Fetch the complete documentation index at: https://docs.cuadra.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Files > List files with optional filtering by status or resource. To list files for a specific chat: GET /v1/files?resourceType=chat&resourceId={chat_id} To list files for a specific dataset: GET /v1/files?resourceType=dataset&resourceId={dataset_id} ## OpenAPI ````yaml get /v1/files openapi: 3.1.0 info: title: Cuadra AI API description: >- REST API for AI-powered chat, RAG, and multi-channel messaging. Full documentation at https://docs.cuadra.ai version: 1.0.0 contact: name: Cuadra AI Support url: https://cuadra.ai/support email: support@cuadra.ai license: name: Proprietary url: https://cuadra.ai/terms termsOfService: https://cuadra.ai/terms servers: - url: https://api.cuadra.ai description: Production security: - bearerAuth: [] - oauth2: [] tags: - name: Health description: >- System health monitoring and readiness checks. Essential for load balancers and deployment automation. - name: Models description: >- Manage custom AI model configurations derived from base models. Create, update, and delete with flexible pricing and token limits. - name: Chats description: >- Interact with AI models for intelligent chat completions. Supports streaming and non-streaming modes with message history. - name: Files description: >- Manage file uploads for chat attachments and dataset knowledge bases. Supports automatic processing, chunking, and embedding for RAG. - name: Datasets description: >- Manage RAG knowledge base datasets with versioning and semantic search. Organize uploaded files into searchable knowledge bases. - name: Particles description: >- Manage reusable system prompt particles for AI model behavior. Particles are modular components (role, tone, guardrails, constraints, format) that compose into system prompts. - name: System Prompts description: >- Compose particles into complete system prompts for AI models. System prompts define model behavior through ordered particle compositions with support for version pinning and token budget validation. - name: Usage description: >- Monitor and analyze API usage with detailed token counting. Track usage across models, tenants, and time periods. - name: Artifacts description: >- Manage rich content artifacts generated during chat conversations. Supports markdown, code, HTML, SVG, and Mermaid diagrams. paths: /v1/files: get: tags: - Files summary: List Files description: >- List files with optional filtering by status or resource. To list files for a specific chat: GET /v1/files?resourceType=chat&resourceId={chat_id} To list files for a specific dataset: GET /v1/files?resourceType=dataset&resourceId={dataset_id} operationId: listFiles parameters: - name: statusFilter in: query required: false schema: anyOf: - type: string - type: 'null' title: Statusfilter - name: resourceType in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Filter by resource type: chat, dataset' title: Resourcetype description: 'Filter by resource type: chat, dataset' - name: resourceId in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by resource ID (requires resourceType) title: Resourceid description: Filter by resource ID (requires resourceType) - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 20 title: Limit - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Opaque cursor title: Cursor description: Opaque cursor responses: '200': description: Paginated list of files content: application/json: schema: $ref: '#/components/schemas/FilePage' '404': description: Resource not found (when filtering by resource) '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: FilePage: properties: items: items: $ref: '#/components/schemas/FileOut' type: array title: Items description: List of files nextCursor: anyOf: - type: string - type: 'null' title: Nextcursor description: Cursor for next page (null if no more results) examples: - file_xyz789 hasMore: type: boolean title: Hasmore description: Whether more results are available examples: - true type: object required: - items - hasMore title: FilePage description: >- Paginated file list response. Uses cursor-based pagination for scalability. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError FileOut: properties: id: type: string title: Id description: Unique file identifier examples: - file_abc123 filename: type: string title: Filename description: Original filename examples: - document.pdf contentType: type: string title: Contenttype description: MIME type of the file examples: - application/pdf sizeBytes: type: integer minimum: 0 title: Sizebytes description: File size in bytes examples: - 1048576 sha256: type: string title: Sha256 description: SHA256 hash of file content (for deduplication) examples: - abc123def456... status: type: string enum: - uploading - uploaded - processing - ready - error - failed title: Status description: Processing status examples: - ready isDuplicate: type: boolean title: Isduplicate description: Whether this file reuses existing content (no storage charge) examples: - false storageCharged: type: integer minimum: 0 title: Storagecharged description: Actual storage bytes charged (0 for duplicates) examples: - 1048576 processingStatus: anyOf: - $ref: '#/components/schemas/ProcessingStatus' - type: 'null' description: Detailed processing status createdAt: type: string format: date-time title: Createdat description: File upload timestamp examples: - '2025-01-17T10:00:00Z' processedAt: anyOf: - type: string format: date-time - type: 'null' title: Processedat description: When file processing completed examples: - '2025-01-17T10:02:30Z' associations: anyOf: - items: $ref: '#/components/schemas/FileAssociationOut' type: array - type: 'null' title: Associations description: >- Resources this file is associated with (included when expanded with ?expand[]=associations) source: type: string title: Source description: 'Request origin: api, m2m, connector' default: api examples: - api - m2m - connector sourceDetail: anyOf: - type: string - type: 'null' title: Sourcedetail description: 'Specific source: dashboard, google_drive, notion, etc.' examples: - dashboard - google_drive connectorMetadata: anyOf: - $ref: '#/components/schemas/ConnectorMetadata' - type: 'null' description: >- Metadata from external connector (Google Drive, Notion, etc.). Only present for connector-synced files. type: object required: - id - filename - contentType - sizeBytes - sha256 - status - isDuplicate - storageCharged - createdAt title: FileOut description: >- File response schema - COMPOSITE SCHEMA. Combines data from multiple sources for API simplicity: - FileEntity: id, filename, created_at (logical file) - FileContent: sha256, size_bytes, content_type, status, processed_at (physical content) - Computed: isDuplicate, storageCharged (deduplication logic) - Relationships: associations (file-resource links) Used for GET /v1/files/{id} and POST /v1/files responses. Deduplication info: - isDuplicate: Whether this file reuses existing content - storageCharged: Actual storage bytes charged (0 for duplicates) - sha256: Content hash for deduplication tracking ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ProcessingStatus: properties: progress: type: integer maximum: 100 minimum: 0 title: Progress description: Processing progress percentage (0-100) default: 0 examples: - 75 error: anyOf: - type: string - type: 'null' title: Error description: Error message if processing failed examples: - Failed to extract text from PDF type: object title: ProcessingStatus description: File processing status details. FileAssociationOut: properties: resourceType: type: string title: Resourcetype description: Type of associated resource examples: - chat resourceId: type: string title: Resourceid description: ID of associated resource examples: - chat_abc123 createdAt: type: string format: date-time title: Createdat description: When association was created examples: - '2025-01-17T10:00:00Z' type: object required: - resourceType - resourceId - createdAt title: FileAssociationOut description: File association details. ConnectorMetadata: properties: externalId: type: string title: Externalid description: Provider's unique identifier for the resource examples: - 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs externalUrl: anyOf: - type: string - type: 'null' title: Externalurl description: Web link to view the file in the source system examples: - https://docs.google.com/document/d/1Bxi... externalPath: anyOf: - type: string - type: 'null' title: Externalpath description: >- Human-readable hierarchical path from the source system, built from the folder/page structure during sync. Use this to disambiguate files with the same name that originate from different locations in the provider (e.g. two files named 'report.md' in different Notion pages). examples: - /Marketing/Q4 Reports/Revenue.pdf - /Engineering/Onboarding/Getting Started modifiedBy: anyOf: - type: string - type: 'null' title: Modifiedby description: Who last modified the file in the source system examples: - Jane Doe - jane@acme.com sourceModifiedAt: anyOf: - type: string format: date-time - type: 'null' title: Sourcemodifiedat description: When the file was last modified in the source system examples: - '2026-01-10T14:30:00Z' labels: anyOf: - items: type: string type: array - type: 'null' title: Labels description: Tags or labels from the source system examples: - - important - q4-review extra: anyOf: - type: object - type: 'null' title: Extra description: Additional provider-specific metadata examples: - shared: true starred: false type: object required: - externalId title: ConnectorMetadata description: >- Metadata for files synced from external connectors (Google Drive, Notion, etc.). This is the structured, API-exposed metadata. The raw provider response is stored separately and never exposed. Key fields: - ``externalId``: Unique resource identifier in the source system. - ``externalPath``: Hierarchical path built from the provider's folder/page structure during sync (e.g. ``/Sales/Q4/report.md``). Use this to distinguish files with identical names that live in different locations. - ``sourceModifiedAt``: Last modification timestamp from the provider. All fields except ``externalId`` are optional since different providers have different data available. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT token from Stytch B2B authentication (magic link, SSO, or M2M) oauth2: type: oauth2 flows: clientCredentials: tokenUrl: https://auth.cuadra.ai/oauth/token scopes: chats:invoke: Invoke chat completions (billable) chats:read: Read and list chats chats:write: Create and update chats chats:delete: Delete chats chats:admin: Full chat access (read/write/delete/invoke) models:read: Read model configurations models:write: Create and update models models:delete: Delete models models:admin: Full access to models (grants read + write + delete) datasets:read: Read and list datasets and snapshots datasets:write: Create and update datasets and snapshots datasets:delete: Delete datasets and snapshots datasets:admin: Full dataset access (read/write/delete) files:read: Read, list, and download files files:write: Upload, associate, and reprocess files files:delete: Delete files (single and bulk) files:admin: Full access to files (grants read + write + delete) particles:read: View particles and particle versions particles:write: Create and update particles particles:delete: Delete particles particles:admin: Full particle access (read/write/delete) system-prompts:read: View system prompts and compositions system-prompts:write: Create and update system prompts system-prompts:delete: Delete system prompts system-prompts:admin: Full system prompt access (read/write/delete) usage:read: Read usage and billing information usage:admin: Full access to usage data (grants read) connections:read: View external connections and sync status connections:write: Create and update external connections connections:delete: Delete connections and sync configurations connections:admin: Full connection access (read/write/delete) channels:read: View channels and channel configuration channels:write: Create and update channels channels:delete: Delete channels and release phone numbers channels:admin: Full channel access (read/write/delete) org:admin: Full resource access, manage members org:owner: 'Owner: all access including billing' chat:write: Delete and manage chats ````