# 4. File Storage

### File API

#### Upload a File

| Parameters | Type                  |
| ---------- | --------------------- |
| metadata   | FileMetadataReq       |
| file       | ArrayBuffer \| Buffer |
| fileType   | string                |

Response:

* FileMetadataRes: The File metadata.

**FileMetadataReq type:**

```typescript
interface FileMetadataReq {
  name: string;
  source: string;
  tags?: string[];
  title?: string;
  description?: string;
  dateCreated?: number;
  lastUpdated?: number;
}
```

**Response type:**

```typescript
interface FileMetadataRes {
  fileId: string;
  name: string;
  source: string;
  tags?: string[];
  title?: string;
  description?: string;
  dateCreated: number;
  lastUpdated: number;
  status: FileStatus;
  contentUrl?: string;
  contentPublic: boolean;
  permissions: FilePermissions;
}

interface FileStatus {
  status: string;
  size?: number;
}

interface FilePermissions {
  userId: string;
  contentReadable: boolean;
}
```

**Example:**

```typescript
try {
    const meta = {
                "name": "testFileName",
                "source": "applicationName",
                "tags": [
                    "iphone",
                    "photo",
                ]
            };
    const file = []; // ArrayBuffer or Buffer

    const result = await hat.files().uploadFile(meta, file, "image/png");

    if (result.parsedBody) {
        // result.parsedBody contains the File metadata.
    }
} catch (error) {
  // Failed to upload a file...
}
```

**Example response:**

```typescript
{
  "fileId": "applicationnametestfilename-5",
  "name": "testFileName",
  "source": "applicationName",
  "dateCreated": "2020-03-04T13:13:37.041Z",
  "lastUpdated": "2020-03-04T13:13:37.042Z",
  "tags": [
    "iphone",
    "photo"
  ],
  "status": {
    "status": "New"
  },
  "contentUrl": "https://hubat-net-hatservice-v3ztbxc9civz-storages3bucket-m0gs7co0oyi2.s3.eu-west-1.amazonaws.com/testing.hubat.net/applicationnametestfilename-5?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190404T131337Z&X-Amz-SignedHeaders=host%3Bx-amz-server-side-encryption&X-Amz-Expires=299&X-Amz-Credential=AKIAICFRCZUZIP4PQ64A%2F20190404%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Signature=6e7b112fca980dafe9935e8c849dfdb7e4e49abb658947909ec35c12370247b2",
  "contentPublic": false,
  "permissions": [
    {
      "userId": "de35e18d-147f-4664-8de7-409abf881754",
      "contentReadable": true
    }
  ]
}
```

#### Mark a file as public

| Parameters | Type   |
| ---------- | ------ |
| fileId     | string |

Response:

* FileMetadataRes: The File metadata.

**Example:**

```typescript
try {
    const result = await hat.files().markFileAsPublic("file-id");

    if (result.parsedBody) {
        // result.parsedBody contains the File metadata.
    }
} catch (error) {
  // Failed to mark a file as public...
}
```

#### Mark a file as private

| Parameters | Type   |
| ---------- | ------ |
| fileId     | string |

Response:

* FileMetadataRes: The File metadata.

**Example:**

```typescript
try {
    const result = await hat.files().markFileAsPrivate("file-id");

    if (result.parsedBody) {
        // result.parsedBody contains the File metadata.
    }
} catch (error) {
  // Failed to mark a file as private...
}
```

#### Update File metadata

| Parameters | Type   |
| ---------- | ------ |
| fileId     | string |

Response:

* FileMetadataRes: The File metadata.

**Example:**

```typescript
try {
    const meta = {
                "name": "differentFileName",
                "source": "applicationName",
                "tags": [
                    "iphone",
                    "photo",
                    "extra tag"
                ]
            };
    const result = await hat.files().updateFileParameters("file-id", meta);

    if (result.parsedBody) {
        // result.parsedBody contains the File metadata.
    }
} catch (error) {
  // Failed to update file's metadata...
}
```

#### Search Files

| Parameters | Type            |
| ---------- | --------------- |
| metadata   | FileMetadataReq |

Response:

* Array: An array of File metadata.

**Example:**

```typescript
try {
    const meta = {
                "name": "",
                "source": "applicationName",
                "tags": [
                    "iphone",
                    "photo",
                ]
            };
    const result = await hat.files().searchFiles(meta);

    if (result.parsedBody) {
        // result.parsedBody contains an array of File metadata.
        // The result contains all the files with the tags "iphone" and "photo" with the same source.
    }
} catch (error) {
  // Failed to search for Files...
}
```

#### Delete File

| Parameters | Type   |
| ---------- | ------ |
| fileId     | string |

Response:

* FileMetadataRes: The File metadata.

**Example:**

```typescript
try {
    const result = await hat.files().deleteFile("file-id");

    if (result.parsedBody) {
        // result.parsedBody contains the File metadata.
    }
} catch (error) {
  // Failed to delete the File...
}
```

#### Generate File content URL

| Parameters | Type   |
| ---------- | ------ |
| fileId     | string |

Response:

* string: The URL to the content.

**Example:**

```typescript
const url = hat.files().getFileContentUrl("file-id");

console.log(url); 
// will print:
// https://<hat-url>/api/v2.6/files/content/<file-id>>

// The file will be available in this URL.
// Note: if the file is private, will need to pass the authentication token as 
// a header to access the file.
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dataswyft.com/build/advanced-topics/pda-authentication/password-management/tutorials/data-api/4.-file-storage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.