> ## Documentation Index > Fetch the complete documentation index at: https://docs.varg.ai/llms.txt > Use this file to discover all available pages before exploring further. # List files with lineage > Lists uploads and generated files in one list, newest first, each with its lineage (tool, model, prompt, cost) and favorite flag. Compared to `GET /files` it can filter by folder, creator and favorites. Uploads have `lineage: null`. Multi-value filters (`kind`, `tool`) accept repeated parameters or a comma-separated value and are OR-combined. A malformed `created_by` or `creator_api_key_id` is ignored rather than rejected. ## OpenAPI ````yaml /openapi.yaml get /resources/files openapi: 3.1.0 info: title: varg API version: 2.0.0 description: | Unified REST API for AI media generation at `api.varg.ai/v2`. One API key, ~80 models across 8 providers, async jobs, stable output URLs on `s3.varg.ai`, files with lineage, and transparent credit billing (1 credit = 1 cent = $0.01). **The async job pattern:** every generation request returns `202 Accepted` with a job object (`status: queued`). Poll `GET /jobs/{id}` until the job reaches a terminal status (`completed`, `failed`, or `cancelled`), then read `output.outputs[0].url`. Alternatively, set `options.webhook_url` in the request to receive an HMAC-signed callback when the job finishes. servers: - url: https://api.varg.ai/v2 security: - bearerAuth: [] tags: - name: Generation description: >- Create generation jobs (image, video, speech, music, transcription, ffmpeg, render, pipeline) - name: Tools description: Discover tools, their schemas, and call any tool generically - name: Jobs description: Poll and manage job lifecycle - name: Files description: Upload, import, probe, and manage files - name: Folders description: Group files into folders and file generated output automatically - name: Lineage description: Resolve which job produced a file - name: Presets description: Browse and apply reusable parameter values — voices, styles - name: Templates description: Browse, publish, use and render community templates - name: Pricing description: Estimate costs and browse the price catalog - name: Billing description: Balance, usage, and transaction history - name: Analytics description: >- Spend, runs and files over time — summaries, time series, breakdowns, activity - name: Account description: Identity and API key management paths: /resources/files: get: tags: - Files summary: List files with lineage description: | Lists uploads and generated files in one list, newest first, each with its lineage (tool, model, prompt, cost) and favorite flag. Compared to `GET /files` it can filter by folder, creator and favorites. Uploads have `lineage: null`. Multi-value filters (`kind`, `tool`) accept repeated parameters or a comma-separated value and are OR-combined. A malformed `created_by` or `creator_api_key_id` is ignored rather than rejected. operationId: listResourceFiles parameters: - name: kind in: query description: >- Media kind (`image`, `video`, `audio`) and/or origin (`upload`, `generated`). Unknown values are ignored. schema: type: array items: type: string enum: - image - video - audio - upload - generated style: form explode: false example: image,generated - name: tool in: query description: >- Restrict to files produced by these tools. Unknown values are ignored. schema: type: array items: type: string enum: - image - video - speech - music - render - transcription - ffmpeg style: form explode: false - name: search in: query description: Matches the prompt, text or code of the job that produced the file. schema: type: string - name: workspace in: query description: Folder id or slug, or `unfiled` for files in no folder. schema: type: string - name: favorites in: query description: When `true`, only files the caller has favorited. schema: type: boolean - name: created_by in: query description: Only files created by this user id. schema: type: string format: uuid - name: creator_api_key_id in: query description: Only files created through this API key id. schema: type: string format: uuid - name: from in: query description: Earliest creation time (ISO 8601). schema: type: string format: date-time - name: to in: query description: Latest creation time (ISO 8601). schema: type: string format: date-time - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 24 - name: cursor in: query description: Offset returned as `nextCursor` by the previous page. schema: type: integer default: 0 minimum: 0 responses: '200': description: Page of files content: application/json: schema: $ref: '#/components/schemas/ResourceFileList' '401': $ref: '#/components/responses/Unauthorized' '404': description: Unknown folder (or not owned by the caller) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: workspace_not_found message: Unknown workspace components: schemas: ResourceFileList: type: object required: - data - nextCursor properties: data: type: array items: $ref: '#/components/schemas/ResourceFile' nextCursor: type: - integer - 'null' ErrorResponse: type: object properties: error: type: object properties: code: type: string example: model_not_found message: type: string example: 'Unknown model: flux-shnell' details: {} ResourceFile: type: object properties: id: type: string source: type: string enum: - attachment - gateway description: '`gateway` for generated files, `attachment` for uploads.' url: type: string filename: type: - string - 'null' title: type: - string - 'null' subtitle: type: - string - 'null' media_type: type: - string - 'null' size: type: - integer - 'null' created_at: type: string format: date-time hash: type: - string - 'null' thumbnail_url: type: - string - 'null' origin: type: string enum: - upload - generated created_by: type: - string - 'null' format: uuid created_by_profile: type: - object - 'null' properties: display_name: type: - string - 'null' avatar_url: type: - string - 'null' creator_type: type: - string - 'null' enum: - user - api_key - system - null created_by_api_key: type: - object - 'null' description: >- The API key the file was created through. Only set when `creator_type` is `api_key`. properties: id: type: string format: uuid key_preview: type: string example: varg_a1b2...c3d4 name: type: - string - 'null' metadata: type: - object - 'null' additionalProperties: true lineage: oneOf: - $ref: '#/components/schemas/ResourceLineage' - type: 'null' is_favorite: type: boolean ResourceLineage: type: object description: >- The job that produced a file. Detail responses carry extra fields (`provider`, `breakdown`, `created_at`, `file`). additionalProperties: true properties: job_id: type: string tool: type: string example: image model: type: - string - 'null' prompt: type: - string - 'null' provider: type: - string - 'null' cost_cents: type: - integer - 'null' parent_job_id: type: - string - 'null' root_job_id: type: - string - 'null' children_count: type: integer total_cost_cents: type: - integer - 'null' description: Cost of this job plus every sub-generation it spawned. children_by_tool: type: array items: type: object properties: tool: type: string count: type: integer cost_cents: type: integer breakdown: type: array description: >- Per-job cost lines behind `total_cost_cents`. Only on the detail endpoint, and only when the job has children. items: type: object properties: job_id: type: string tool: type: string model: type: - string - 'null' status: type: - string - 'null' cost_cents: type: integer is_root: type: boolean output_count: type: integer description: Total files the job produced. output_index: type: - integer - 'null' description: 1-based position of this file among the job's outputs. primary_file_id: type: - string - 'null' created_at: type: string format: date-time input: type: object additionalProperties: true file: type: object additionalProperties: true responses: Unauthorized: description: Missing or invalid API key / JWT content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: value: error: code: unauthorized message: Invalid or missing API key or JWT securitySchemes: bearerAuth: type: http scheme: bearer description: | varg API key (`varg_...`). Get one at [app.varg.ai](https://app.varg.ai) or run `bunx vargai login`. App sessions may alternatively send a Supabase JWT. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.