Files

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

The file model

Arguments

idobjectIdauto

Unique identifier for the file

aliasesarray of String

An array of alternative names or aliases associated with the file.

chunk_sizeintauto

The size of data chunks used during file upload.

content_typestring

The MIME type or content type of the file.

datafiledata

File content, base64-encoded when created or updated through the API.

date_createddateauto

The date and time when the file object was initially created.

date_uploadeddateauto

The date and time when the file was uploaded.

filenamestring

The name of the uploaded file.

heightint

The height dimension of the file, applicable for image files.

lengthintauto

The length or size of the file in bytes.

md5stringauto

The MD5 hash value of the file content.

metadataobject

Arbitrary data for storing additional information about the file.

privateboolean

Indicates the file is private and not served publicly from the CDN.

urlstringauto

The URL providing direct access to the file.

widthint

The width dimension of the file, applicable for image files.

The file model

{
    "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.

👉

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

Arguments

content_typestring

The MIME type or content type of the file. If omitted, it's detected automatically from the file data.

dataobjectrequired

The uploaded file in binary or base64 string

filenamestring

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.

heightint

The height dimension of the file, only applicable for image files.

widthint

The width dimension of the file, only applicable for image files.

POST/:files

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,
});

Response

{
    "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

idobjectIdrequired

The id of the file to retrieve.

GET/:files

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

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

The file model

{
    "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

idobjectIdrequired

The id of the file you wish to update.

PUT/:files

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: {
      ...
    },
  },
});

The file model

{
    "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

expandstring

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 for more details.

fieldsstring

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.

includeobject

Include one or more arbitrary queries in the response which are potentially related to the main query.

See including for more details.

limitint

Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.

pageint

The page number of results to return given the specified or default limit.

searchstring

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 for more details.

sortstring

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 for more details.

whereobject

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 for more details.

GET/:files

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

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

The file model

[
  {
    "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"
  }
]

Delete a file

Delete a file.

Arguments

idobjectIdrequired

The id of the file you wish to delete.

DELETE/:files

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

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

The file model

{
  "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"
}

← Back: Webhooks Next: Notes →