# Files

Source: https://developers.swell.is/backend-api/files

Every file you upload to Swell will be retrievable from this endpoint. Files represent uploads to our CDN.

## The file model

### Arguments

- `id` (objectId, auto): Unique identifier for the file
- `aliases` (array of String): An array of alternative names or aliases associated with the file.
- `chunk_size` (int, auto): The size of data chunks used during file upload.
- `content_type` (string): The MIME type or content type of the file.
- `data` (filedata): File content, base64-encoded when created or updated through the API.
- `date_created` (date, auto): The date and time when the file object was initially created.
- `date_uploaded` (date, auto): The date and time when the file was uploaded.
- `filename` (string): The name of the uploaded file.
- `height` (int): The height dimension of the file, applicable for image files.
- `length` (int, auto): The length or size of the file in bytes.
- `md5` (string, auto): The MD5 hash value of the file content.
- `metadata` (object): Arbitrary data for storing additional information about the file.
- `private` (boolean): Indicates the file is private and not served publicly from the CDN.
- `url` (string, auto): The URL providing direct access to the file.
- `width` (int): The width dimension of the file, applicable for image files.

### Example response

```json
{
    "length": 6028032,
    "chunkSize": 261120,
    "filename": "image.jpg",
    "content_type": "image/jpeg",
    "date_created": "2024-01-03T09:22:39.192Z",
    "date_uploaded": "2024-01-03T09:22:40.032Z",
    "height": 2075,
    "md5": "ed8b7b4eea7b8d54662b86fd707f09f6",
    "url": "https://cdn.swell.store/6595275fc22a5b00127df144",
    "width": 3120,
    "id": "6595275fc22a5b00127df144"
}
```


## Create a file

Create a new file.

> **Tip:** Note: The maximum size for uploading files using the Files API is **10 Megabytes**.

### Arguments

- `content_type` (string): The MIME type or content type of the file. If omitted, it's detected automatically from the file data.
- `data` (object, required): The uploaded file in binary or base64 string
  - `$binary` (string): Binary encoded file
  - `$base64` (string): Base64 encoded file
- `filename` (string): Name of the uploaded file. If omitted, a filename is generated in the format `file-{id}.{ext}`, using the extension that matches the file's content type. When the content type can't be determined — as with plain text data — no filename is generated.
- `height` (int): The height dimension of the file, only applicable for image files.
- `width` (int): The width dimension of the file, only applicable for image files.

### Example request

`POST /:files`

**cURL**

```sh
$ curl https://api.swell.store/:files \
  -u store-id:secret-key \
  -d content_type=image/jpeg \
  -d filename=image.jpg \
  -d width=1200 \
  -d height=800 \
  -d data[$base64]="/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsL"
```

**Node**

```javascript
const { swell } = require('swell-node');
const fs = require('fs');

swell.init('store-id', 'secret-key');

const fileData = fs.readFileSync('image.jpg');

await swell.post('/:files', {
  content_type: 'image/jpeg',
  filename: 'image.jpg',
  data: {
    $base64: fileData.toString('base64'),
  },
  width: 1200,
  height: 800,
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$imagedata = file_get_contents('/path/to/image.jpg');

$swell->post('/:files', [
  'content_type' => 'image/jpeg',
  'filename' => 'image.jpg',
  'width' => 1200,
  'height' => 800,
  'data' => [
    '$base64' => base64_encode($imagedata),
  ],
]);
```

### Example response

```json
{
    "length": 4898,
    "chunkSize": 261120,
    "uploadDate": "2024-01-03T11:31:09.153Z",
    "filename": "image.jpg",
    "content_type": "image/jpeg",
    "date_created": "2024-01-03T11:31:09.143Z",
    "date_uploaded": "2024-01-03T11:31:09.158Z",
    "md5": "f082a5c3677bb757e11d738cb6f60624",
    "url": "https://cdn.swell.store/f082a5c3677bb757e11d738cb6f60624/image.jpg",
    "width": 1200,
    "height": 800,
    "id": "6595457d82e01f0012243057"
}
```


## Retrieve a file

Retrieve an existing file using the ID that was returned when created.

### Arguments

- `id` (objectId, required): The id of the file to retrieve.

### Example request

`GET /:files`

**cURL**

```sh
$ curl https://api.swell.store/:files/6595457d82e01f0012243057 \
  -u store-id:secret-key
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/:files/{id}', {
  id: '6595457d82e01f0012243057'
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/:files/{id}', [
  'id' => '6595457d82e01f0012243057'
]);
```

### Example response

```json
{
    "length": 4898,
    "chunkSize": 261120,
    "uploadDate": "2024-01-03T11:31:09.153Z",
    "filename": "image.jpg",
    "content_type": "image/jpeg",
    "date_created": "2024-01-03T11:31:09.143Z",
    "date_uploaded": "2024-01-03T11:31:09.158Z",
    "md5": "f082a5c3677bb757e11d738cb6f60624",
    "url": "https://cdn.swell.store/f082a5c3677bb757e11d738cb6f60624/image.jpg",
    "id": "6595457d82e01f0012243057"
}
```


## Update a file

Updates an existing file using the ID that was returned when created. Updating performs a merge operation. To explicitly override values such as arrays, use the $set operator.

### Arguments

- `id` (objectId, required): The id of the file you wish to update.
- `data` (filedata): File content, base64-encoded when created or updated through the API.
- `filename` (string): The name of the uploaded file.
- `aliases` (array of String): An array of alternative names or aliases associated with the file.
- `metadata` (object): Arbitrary data for storing additional information about the file.
- `private` (boolean): Indicates the file is private and not served publicly from the CDN.
- `width` (int): The width dimension of the file, applicable for image files.
- `height` (int): The height dimension of the file, applicable for image files.

### Example request

`PUT /:files`

**cURL**

```sh
$ curl https://api.swell.store/:files/6595457d82e01f0012243057 \
  -u store-id:secret-key \
  -d width=1200 \
  -X PUT
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.put('/:files/{id}', {
  id: '6595457d82e01f0012243057',
  width: 1200,
  // use $set to override values
  $set: {
    metadata: {
      ...
    },
  },
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->put('/:files/{id}', [
  'id' => '6595457d82e01f0012243057',
  'width' => 1200,
  // use $set to override values
  '$set' => {
    'metadata' => [
      ...
    ],
  ],
]);
```

### Example response

```json
{
    "length": 4898,
    "chunkSize": 261120,
    "uploadDate": "2024-01-03T11:31:09.153Z",
    "filename": "image.jpg",
    "content_type": "image/jpeg",
    "date_created": "2024-01-03T11:31:09.143Z",
    "date_uploaded": "2024-01-03T11:31:09.158Z",
    "md5": "f082a5c3677bb757e11d738cb6f60624",
    "url": "https://cdn.swell.store/f082a5c3677bb757e11d738cb6f60624/image.jpg",
    "width": 1200,
    "id": "6595457d82e01f0012243057"
}
```


## List all files

Return a list of files.

### Arguments

- `expand` (string): Expand link fields and child collections by using the expand argument.

  - For example, `expand=account` would return a related customer account if one exists.

  When the field represents a collection, you can specify the query limit.

  - For example, `expand=variants:10` would return up to 10 records of the variants collection.

  See [expanding](https://developers.swell.is/backend-api/querying/expanding) for more details.
- `fields` (string): Returns only the specified fields in the result.

  - For example `fields=name,slug` would return only the fields `name` and `slug` in the response.

  Supports nested object and array fields using dot-notation.

  - For example, `items.product_id`. The product `id` is always returned.
- `include` (object): Include one or more arbitrary queries in the response which are potentially related to the main query.

  See [including](https://developers.swell.is/backend-api/querying/including) for more details.
- `limit` (int): Limit the number of records returned, ranging between `1` and `1000`. Defaults to `15`. Default: `15`.
- `page` (int): The page number of results to return given the specified or default `limit`.
- `search` (string): A text search is performed using the search argument. Searchable fields are defined by the model.

  - For example, `search=red` would return records containing the word "red" anywhere in the defined text fields.

  See [searching](https://developers.swell.is/backend-api/querying/searching) for more details.
- `sort` (string): Expression to sort results by using a format similar to a SQL sort statement.

  - For example, `sort=name asc` would return records sorted by name ascending.

  See [sorting](https://developers.swell.is/backend-api/querying/sorting) for more details.
- `where` (object): An object with criteria to filter the result.

  - For example, `active=true` would return records containing a field `active` with the value `true`.

  It's also possible to use query operators, for example, `$eq`, `$ne`, `$gt`, and more.

  See [querying](https://developers.swell.is/backend-api/querying) for more details.

### Example request

`GET /:files`

**cURL**

```sh
$ curl https://api.swell.store/:files?limit=25&page=1 \
  -u store-id:secret-key \
  -G
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/:files', {
  limit: 25,
  page: 1,
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/:files', [
  'limit' => 25,
  'page' => 1,
]);
```

### Example response

```json
{
  "count": 2,
  "results": [
    {
      "length": 4898,
      "chunkSize": 261120,
      "uploadDate": "2024-01-03T11:31:09.153Z",
      "filename": "image.jpg",
      "content_type": "image/jpeg",
      "date_created": "2024-01-03T11:31:09.143Z",
      "date_uploaded": "2024-01-03T11:31:09.158Z",
      "md5": "f082a5c3677bb757e11d738cb6f60624",
      "url": "https://cdn.swell.store/f082a5c3677bb757e11d738cb6f60624/image.jpg",
      "id": "6595457d82e01f0012243057"
    },
    {
      "length": 5120,
      "chunkSize": 261120,
      "uploadDate": "2024-01-04T09:12:44.201Z",
      "filename": "other-image.jpg",
      "content_type": "image/jpeg",
      "date_created": "2024-01-04T09:12:44.190Z",
      "date_uploaded": "2024-01-04T09:12:44.205Z",
      "md5": "3c9a1de5b7f204e8c6d1b0a95e4f7d38",
      "url": "https://cdn.swell.store/3c9a1de5b7f204e8c6d1b0a95e4f7d38/other-image.jpg",
      "id": "65965a1c82e01f0012243099"
    }
  ],
  "page": 1,
  "page_count": 1,
  "limit": 25
}
```


## Delete a file

Delete a file.

### Arguments

- `id` (objectId, required): The id of the file you wish to delete.

### Example request

`DELETE /:files`

**cURL**

```sh
$ curl https://api.swell.store/:files/6595457d82e01f0012243057 \
  -u store-id:secret-key \
  -X DELETE
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.delete('/:files/{id}', {
  id: '6595457d82e01f0012243057',
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->delete('/:files/{id}', [
  'id' => '6595457d82e01f0012243057',
]);
```

### Example response

```json
{
  "length": 4898,
  "chunkSize": 261120,
  "uploadDate": "2024-01-03T11:31:09.153Z",
  "filename": "image.jpg",
  "content_type": "image/jpeg",
  "date_created": "2024-01-03T11:31:09.143Z",
  "date_uploaded": "2024-01-03T11:31:09.158Z",
  "md5": "f082a5c3677bb757e11d738cb6f60624",
  "url": "https://cdn.swell.store/f082a5c3677bb757e11d738cb6f60624/image.jpg",
  "id": "6595457d82e01f0012243057"
}
```