# Files ## Create `client.vals.files.create(stringvalId, FileCreateParamsparams, RequestOptionsoptions?): FileCreateResponse` **post** `/v2/vals/{val_id}/files` Create a new file, project val or directory ### Parameters - **valId:** `string` - **FileCreateParams:** `Variant0 | Variant1` - `FileCreateParamsBase` - `Variant0 extends FileCreateParamsBase` - `Variant1 extends FileCreateParamsBase` ### Returns - `FileCreateResponse` A File or Directory's Metadata - **id:** `string` The id of the resource - **links:** `Links` - **html:** `string` The URL of this resource on Val Town - **module:** `string` The URL of this resource's source code as a module - **self:** `string` The URL of this resource on this API - **endpoint:** `string` This resource's web endpoint, where it serves a website or API - **name:** `string` - **path:** `string` - **type:** `"directory" | "file" | "interval" | 3 more` - `"directory"` - `"file"` - `"interval"` - `"http"` - `"email"` - `"script"` - **updatedAt:** `string` - **version:** `number` ### Example ```node import ValTown from '@valtown/sdk'; const client = new ValTown(); const file = await client.vals.files.create('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { path: 'path', type: 'directory', }); console.log(file.id); ``` ## Retrieve `client.vals.files.retrieve(stringvalId, FileRetrieveParamsquery, RequestOptionsoptions?): PageCursorURL` **get** `/v2/vals/{val_id}/files` Get metadata for files and directories in a val. If path is an empty string, returns files at the root directory. ### Parameters - **valId:** `string` - **query:** `FileRetrieveParams` - **limit:** `number` Maximum items to return in each paginated response - **offset:** `number` Number of items to skip in order to deliver paginated results - **path:** `string` Path to a file or directory (e.g. 'dir/subdir/file.ts'). Pass in an empty string to represent the root directory. - **recursive:** `boolean` Whether to recursively act on all files in the project - **branch\_id:** `string` Id to query - **version:** `number` Specific branch version to query ### Returns - `FileRetrieveResponse` A File or Directory's Metadata - **id:** `string` The id of the resource - **links:** `Links` - **html:** `string` The URL of this resource on Val Town - **module:** `string` The URL of this resource's source code as a module - **self:** `string` The URL of this resource on this API - **endpoint:** `string` This resource's web endpoint, where it serves a website or API - **name:** `string` - **path:** `string` - **type:** `"directory" | "file" | "interval" | 3 more` - `"directory"` - `"file"` - `"interval"` - `"http"` - `"email"` - `"script"` - **updatedAt:** `string` - **version:** `number` ### Example ```node import ValTown from '@valtown/sdk'; const client = new ValTown(); // Automatically fetches more pages as needed. for await (const fileRetrieveResponse of client.vals.files.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { limit: 1, offset: 0, path: 'path', recursive: true, })) { console.log(fileRetrieveResponse.id); } ``` ## Update `client.vals.files.update(stringvalId, FileUpdateParamsparams, RequestOptionsoptions?): FileUpdateResponse` **put** `/v2/vals/{val_id}/files` Update a file's content ### Parameters - **valId:** `string` - **params:** `FileUpdateParams` - **path:** `string` Query param: Path to a file or directory (e.g. 'dir/subdir/file.ts'). Pass in an empty string to represent the root directory. - **branch\_id:** `string` Query param: The specified branch of the resource. Defaults to main if not provided. - **content:** `string` Body param: File and val content. An empty string will create an empty file. When creating a directory, the content should be null or undefined. - **name:** `string` Body param: - **parent\_path:** `string | null` Body param: Path to the directory you'd like to move this file to (e.g. 'folder1/folder2') - **type:** `"file" | "interval" | "http" | 2 more` Body param: - `"file"` - `"interval"` - `"http"` - `"email"` - `"script"` ### Returns - `FileUpdateResponse` A File or Directory's Metadata - **id:** `string` The id of the resource - **links:** `Links` - **html:** `string` The URL of this resource on Val Town - **module:** `string` The URL of this resource's source code as a module - **self:** `string` The URL of this resource on this API - **endpoint:** `string` This resource's web endpoint, where it serves a website or API - **name:** `string` - **path:** `string` - **type:** `"directory" | "file" | "interval" | 3 more` - `"directory"` - `"file"` - `"interval"` - `"http"` - `"email"` - `"script"` - **updatedAt:** `string` - **version:** `number` ### Example ```node import ValTown from '@valtown/sdk'; const client = new ValTown(); const file = await client.vals.files.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { path: 'path' }); console.log(file.id); ``` ## Delete `client.vals.files.delete(stringvalId, FileDeleteParamsparams, RequestOptionsoptions?): void` **delete** `/v2/vals/{val_id}/files` Deletes a file or a directory. To delete a directory and all of its children, use the recursive flag. To delete all files, pass in an empty path and the recursive flag. ### Parameters - **valId:** `string` - **params:** `FileDeleteParams` - **path:** `string` Path to a file or directory (e.g. 'dir/subdir/file.ts'). Pass in an empty string to represent the root directory. - **recursive:** `boolean` Whether to recursively act on all files in the project - **branch\_id:** `string` The specified branch of the resource. Defaults to main if not provided. ### Example ```node import ValTown from '@valtown/sdk'; const client = new ValTown(); await client.vals.files.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { path: 'path', recursive: true }); ``` ## Get Content `client.vals.files.getContent(stringvalId, FileGetContentParamsparams, RequestOptionsoptions?): Response` **get** `/v2/vals/{val_id}/files/content` Download file content ### Parameters - **valId:** `string` - **params:** `FileGetContentParams` - **path:** `string` Query param: Path to a file or directory (e.g. 'dir/subdir/file.ts'). Pass in an empty string to represent the root directory. - **branch\_id:** `string` Query param: Id to query - **version:** `number` Query param: Specific branch version to query - **cacheControl:** `string` Header param: - **ifMatch:** `string` Header param: - **ifModifiedSince:** `string` Header param: - **ifNoneMatch:** `string` Header param: - **ifUnmodifiedSince:** `string` Header param: ### Returns - **unnamed\_schema\_1:** `Response` ### Example ```node import ValTown from '@valtown/sdk'; const client = new ValTown(); const response = await client.vals.files.getContent('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { path: 'path' }); console.log(response); const content = await response.blob(); console.log(content); ```